docs: governance workstream exploration and context consolidation

docs/notes/ai-ethics-security-principles.md

@@ -0,0 +1,89 @@
+# Exploration Note: Core Principles — AI Ethics & Security
+
+## Purpose
+
+Brief for a `/grill-with-docs` session. Goal: define the scope, structure, and tier placement of core principles governing AI ethics and security before writing any content.
+
+## What we want to build
+
+A set of guiding principles covering:
+
+- **Ethics** — responsible use of AI in development (trust, transparency, human oversight, bias, accountability)
+- **Security** — secure use of AI tooling (prompt injection, credential handling, supply chain, code review hygiene, data exposure)
+- **Other candidates** — privacy, auditability, scope creep (AI doing more than asked), agent autonomy limits
+
+These would live somewhere in this repo and be deployed to `~/.claude/` via `install.sh`.
+
+## Key question the grill must resolve
+
+**Tier placement** — the two-tier CLAUDE.md model (ADR-0005) means this decision has architectural weight:
+
+- **Tier 1 (always-on)** — universal rules in `providers/claude-code/CLAUDE.md`; loaded every session; must apply everywhere
+- **Tier 2 (on-demand)** — topic files in `core/instructions/<topic>.md`; agent reads when task context is relevant
+
+Getting this wrong either bloats every session's context (over-elevated rules) or silently drops rules that should always apply (under-elevated rules).
+
+## What the grill should challenge
+
+1. Which principles are truly universal (always-on) vs. task-specific (on-demand)?
+2. Should ethics and security be one file or separate files?
+3. Is "security" about agent behavior, or developer practice, or both? They have different owners.
+4. Does any of this duplicate what's already in the always-on section of CLAUDE.md (e.g. "require explicit confirmation for irreversible actions" is already there)?
+5. How do project-level overrides interact — can a project suppress a global ethics rule? Should it be able to?
+6. What's the enforcement model — these are instructions to an AI, not code. How do we verify they hold?
+
+## Context the next session needs
+
+- Read `CONTEXT.md` — domain language and existing principles
+- Read `docs/VISION.md` — long-term direction, especially the Management Application (these principles will eventually be configurable in the UI)
+- Read `providers/claude-code/CLAUDE.md` — the always-on section, to avoid duplicating what's already there
+- Read `docs/adr/0005-two-tier-claude-md.md` — rationale for the two-tier model
+- Chunk dev workflow: grill → `/to-prd` → `/to-issues` → `/tdd` → architecture review
+
+## Session flow
+
+### Step 1 — Research sub-agent (run first, before the grill)
+
+Spawn a general-purpose sub-agent to explore the space and return material for the grill to work with. Give it this brief:
+
+> Research AI ethics and AI security principles relevant to a software development context. Cover:
+>
+> - Established frameworks and standards (EU AI Act, NIST AI RMF, OWASP LLM Top 10, IEEE Ethically Aligned Design, Google/Microsoft/Anthropic responsible AI principles)
+> - What practicing dev teams actually use — concrete rules, not abstract values
+> - Security-specific: prompt injection, credential exposure, supply chain risks, code review hygiene, data leakage from context windows
+> - Ethics-specific: human oversight, transparency, bias in generated code, accountability, scope creep / agent autonomy limits
+> - Examples of how other orgs have written these as actionable developer guidelines (not mission statements)
+>
+> Do not just summarize — propose options. For each topic area, give 2–3 distinct approaches with a recommendation and the tradeoff. Flag anything creative or non-obvious. The output will feed a grill session where I'll iterate and refine.
+
+Let the agent return its full output before starting the grill.
+
+### Step 2 — Grill session (`/grill-with-docs`)
+
+Run the grill with both this note and the agent's research output as context. The grill covers two tracks:
+
+**Track A — Structure (what the grill always does)**
+Challenges tier placement, file structure, and terminology against CONTEXT.md and existing ADRs (see "Key questions" above).
+
+**Track B — Content ideation (added scope)**
+Uses the research output to iterate on the actual principles. The grill should:
+- Challenge each proposed principle — is it actionable or a platitude?
+- Force a choice when the agent offers options: pick one, name the tradeoff
+- Identify gaps the research missed
+- Stress-test principles against real scenarios ("a junior dev asks the agent to commit credentials — does this rule catch it?")
+
+The grill closes when both tracks are resolved: structure is decided and a draft principle set is agreed.
+
+---
+
+## Session start — paste this to begin tomorrow
+
+```
+I want to work on core principles for AI ethics and security in this repo. Start by reading docs/notes/ai-ethics-security-principles.md for full context.
+
+Then follow the two-step session flow in that note:
+1. Spawn a general-purpose research sub-agent with the brief from the note. Wait for it to finish.
+2. Run /grill-with-docs with both the note and the agent output as context.
+
+The grill has two tracks: structure (tier placement, file layout) and content ideation (actual principles). Both must be resolved before we close.
+```

docs/notes/team-self-organisation-sprint-brief.md

@@ -0,0 +1,378 @@
+# Team Self-Organisation Sprint — Brief
+
+## Context
+
+We are a new, cross-functional team of four — two developers (one transitioning into a product lead role) and two technical business-side colleagues. We came together from different parts of the organisation, each with different backgrounds and habits. We have been focused on advanced prototyping and building a business case, and now need to shift: from scrappy prototype mode into a functioning team with a shared way of working.
+
+We are building internal AI-enabled tooling, with scope still evolving. Our longer-term ambition is to become the organisation's pathfinder and centre of excellence for AI-assisted development. That future depends on getting our foundations right now — before individual habits calcify and before more people join.
+
+The fastest path to reliable results is a team that collaborates consistently and has standardised how it works with AI. This sprint is an investment in speed, not a detour from it.
+
+## Core design principle: AI-readable by default
+
+Everything this sprint produces must be usable by both humans and AI agents. This is not a nice-to-have — it is a design constraint.
+
+A Confluence page that AI cannot read is incomplete. A convention that is not committed to the repo as context does not exist for Copilot. Every artifact we produce — conventions, templates, constitution, context files — must be structured so that Copilot can load and act on it when needed.
+
+We are not writing documentation *about* how we work with AI. We are building the context layer *through which* AI collaborates with us.
+
+## What This Sprint Is Not
+
+- A process handbook nobody reads
+- A Scrum certification exercise
+- A distraction from shipping
+
+## What This Sprint Produces
+
+By the end of the sprint, the following must exist and be in active use:
+
+1. **Copilot context layer** — `copilot-instructions.md` and a `CONTEXT.md` committed to every repo; the AI-readable foundation everything else references
+2. **Skills library** — agreed set of shared skills (open-source adopted + team-built stubs); committed to `.agents/skills/`
+3. **Development conventions** — branching strategy, commit convention, PR process, code review standards including AI-generated code; committed as context, not only written in Confluence
+4. **AI constitution** — a written working agreement between team members and AI agents: mutual expectations, data handling rules, human-in-the-loop boundaries, quality gates
+5. **Documentation structure** — agreed on what lives where (Azure repo vs Confluence vs SharePoint vs the forge), with a minimal starter structure in place
+6. **Prioritised backlog** — issues for decisions made in the session, plus scoped follow-up grill sessions for topics too complex to resolve in one sitting
+
+## Format
+
+**Part 1 — Half-day discovery session (~3.5 hours)**
+All team members present. Facilitated by the product lead. Use this brief as the agenda.
+
+At the end of each block: capture decisions, write issues for clear actions, flag follow-up grill topics for anything too complex to decide now.
+
+**Part 2 — One-week self-organisation sprint**
+Work through the backlog. Run follow-up grill sessions for flagged topics and generate their issues. Daily standups (15 min). Retro at end. No other ceremonies yet.
+
+---
+
+## Part 1 Session Agenda
+
+### 1. Anti-patterns round (20 min)
+
+Each person names **one thing from a previous team they want to leave behind** — a process, habit, or failure mode they have seen and do not want to repeat.
+
+Record everything. These become the negative space that shapes our decisions in every block that follows.
+
+*Issues to generate:* none directly — outputs feed the other blocks.
+
+---
+
+### 2. Scope alignment (30 min)
+
+Answer these together:
+- What are we actually building for the next 3 months?
+- What is explicitly out of scope for now?
+- Who are our users and stakeholders?
+- What does success look like, and for whom?
+
+No process decision made in this session is meaningful without a shared view of what we are building. If scope remains genuinely unclear after this block, that is issue number one.
+
+*Issues to generate:*
+- "Define and document team scope and 3-month goals" — if not resolved in session
+- "Identify stakeholders and success criteria"
+
+*Follow-up grill if needed:* full scope definition session if the team cannot align in 30 minutes.
+
+---
+
+### 3. Ways of working (45 min)
+
+We use Azure DevOps as our issue tracker. The question is not which tool — it is how we use it.
+
+Decide each of the following. For anything not resolved, flag as a follow-up grill topic.
+
+**Issue management**
+- What fields, labels, and states does every issue have?
+- What makes an issue "ready to pick up"?
+- What is the definition of done for an issue?
+
+**Development conventions**
+- Branching strategy — trunk-based development (recommended: simpler, less merge overhead, suits small teams) or feature branches?
+- Commit convention — do we adopt conventional commits (`feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`)? This enables readable history and automated changelogs.
+- Changelog tooling — if we adopt conventional commits, do we generate changelogs automatically? Decide yes/no; tooling selection can be a follow-up.
+- PR process — minimum reviewers, checklist, merge conditions?
+- AI-generated code review — does AI-generated code require a different or additional review step? What does approval mean when AI wrote the code?
+
+**Workstream model**
+
+How does a piece of work move from idea to shipped? Agree on a shared pattern so everyone handles work the same way. A lightweight but effective model:
+
+```
+Kick-off → Grill (align on what and why) → Artifact (brief, spec, or decision doc)
+  → Issues (break into actionable tasks) → Implement → Review → Commit
+```
+
+The kick-off type shapes the artifact:
+- New feature or improvement → brief or spec
+- Bug → bug description → diagnose
+- Architecture decision → decision doc → ADR after the fact
+- Exploration or uncertainty → grill session → exploration note → issues (optional)
+
+Decide:
+- Do we adopt this pattern or a simpler variant?
+- What do we call each stage? (Use our own language, not borrowed jargon.)
+- Where do the artifacts live? (Repo, Confluence, or both?)
+
+**Ceremonies**
+- Standup cadence and format?
+- Retro frequency?
+- Sprint length?
+
+*Issues to generate:*
+- "Write and commit development conventions to repo" (branching, commits, PR process)
+- "Configure Azure DevOps issue structure" (fields, labels, states, DoD)
+- "Write AI-generated code review standard"
+- "Define and document team workstream model"
+- One issue per unresolved decision flagged as follow-up
+
+---
+
+### 4. AI collaboration standards (45 min)
+
+This block determines the quality floor for everything we produce. Copilot is a collaborator, not a tool — it needs context, standards, and a shared library to produce reliable results.
+
+#### 4a. Context files
+
+Every repo should contain two committed files that AI agents read on demand:
+
+**`copilot-instructions.md`** — the AI's entry point into the repo. Contains:
+- What this repo is and what it does
+- Domain language and key concepts
+- Constraints and conventions (commit style, code style, what not to do)
+- Pointers to other context files
+
+Keep it short — it is an index, not a content dump. AI agents pull what they need from it.
+
+**`CONTEXT.md`** — deeper domain context the AI loads on demand. Contains:
+- Glossary of domain terms used in the codebase
+- Architecture principles and key decisions
+- What is in scope and out of scope for this repo
+
+Decide:
+- What is the minimum content for each file?
+- Who owns and maintains them?
+- Do we start with a shared team template that all projects inherit, or build per-project first? (See appendix for the global vs local decision.)
+
+#### 4b. Skills library
+
+Skills are reusable slash commands for Copilot and other AI tools. They are defined as `SKILL.md` files and stored in `.agents/skills/<skill-name>/SKILL.md` in the repo. This location is read natively by GitHub Copilot, Claude Code, Cursor, and others.
+
+Decide:
+- Which open-source skills do we adopt immediately? (examples: code review, PR description, test generation, commit message)
+- What team-specific skills do we need to build? (examples: domain-specific scaffolding, our PR template, our issue template)
+- Who owns the skills library and how do we add to it?
+- How do we share skills improvements back to the open-source community if relevant?
+
+#### 4c. Workflow patterns
+
+A workflow is a chain of AI interactions for a multi-step task. Examples:
+- `grill → draft → review` for designing a feature
+- `describe bug → reproduce → hypothesise → fix → test` for debugging
+- `write context → generate scaffold → review → refine` for new repo setup
+
+Decide:
+- Do we have recurring multi-step AI tasks that would benefit from a defined workflow?
+- Do we formalise these as shared workflow files, or keep them as team knowledge for now?
+
+*Flag as follow-up grill:* custom agents / Copilot Extensions — worth evaluating but too complex to decide in this session.
+
+#### 4d. Knowledge levelling and sharing
+
+AI knowledge is uneven across the team. Left unaddressed, this creates a single point of failure — one person who knows how to get good results from Copilot, and everyone else dependent on them. That is a risk, not an advantage.
+
+Decide:
+- How do we share what we learn? (a shared Confluence page, a standing agenda item in retro, a skills library contribution pattern?)
+- When someone discovers a better way to use Copilot, how does that become team knowledge rather than personal knowledge?
+- How do we onboard a new team member to our AI collaboration standards quickly?
+- Is there a minimum baseline of AI literacy we expect from every team member? How do we get everyone there?
+
+*Flag as follow-up grill if needed:* AI learning curriculum or structured onboarding for new members.
+
+*Issues to generate:*
+- "Write and commit `copilot-instructions.md` template"
+- "Write and commit `CONTEXT.md` template"
+- "Set up `.agents/skills/` library with initial adopted skills"
+- "Identify and stub team-specific skills needed"
+- "Define knowledge sharing process for AI learnings"
+- "Schedule custom agents evaluation session" (follow-up grill)
+
+---
+
+### 5. AI constitution (30 min)
+
+This is a written working agreement between team members and AI agents. It is committed to the repo and loaded as context — AI agents read and follow it, not just humans. It is a living document, not a compliance checklist.
+
+Write it together. Cover each of the following:
+
+**Enterprise policy alignment**
+- Does the organisation already have an AI usage policy? If yes, our constitution must align with it — not duplicate or contradict it.
+- Are there approved and prohibited AI tools or models we must respect?
+- Are there data classification rules (e.g. confidential, internal, public) that govern what can go into an AI model?
+- Who in the organisation do we need to inform or align with before finalising our constitution?
+
+If enterprise policies exist, reference them explicitly in our constitution rather than restating them. Add only what they do not cover.
+
+**Data rules**
+- What information must never go into an AI model? (PII, credentials, internal strategy, unreleased roadmap)
+- What is the process if someone accidentally shares something they should not have?
+
+**Human-in-the-loop**
+- What actions require human approval before AI executes, commits, or sends?
+- What can AI do autonomously without review?
+- At what point in a task does a human need to check the output?
+
+**Code quality gate**
+- How do we accept AI-generated code before it merges?
+- Does AI-generated code require a specific reviewer or checklist?
+- What does it mean to "own" code that AI wrote?
+
+**Reliability standards**
+- What does good AI output look like for us?
+- When do we trust it and when do we verify it independently?
+- How do we handle confidently wrong AI output?
+
+**Attribution**
+- Do we mark AI-generated code or content? How?
+- Does it matter for internal vs external-facing output?
+
+**Accountability**
+- If an AI agent makes a mistake, who is accountable?
+- How do we detect AI mistakes before they cause problems?
+
+**Feedback loop**
+- How do we evolve these rules as we learn?
+- Where do we capture what works and what does not?
+
+*Issues to generate:*
+- "Write and commit AI constitution v1"
+- "Define process for escalating AI constitution violations or edge cases"
+
+---
+
+### 6. Documentation structure (20 min)
+
+Decide where each type of content lives. The goal is one clear answer per content type — not "it depends."
+
+| Content type                                                     | Candidate location       | Decide                                                |
+| ------------------------------------------------------------------| --------------------------| -------------------------------------------------------|
+| Repo context files (CONTEXT.md, copilot-instructions.md, skills) | Azure repo               | Likely yes — source of truth for AI                   |
+| Architecture Decision Records (ADRs)                             | Azure repo               | Recommended — close to the code they document         |
+| Work artifacts (briefs, specs, decision docs)                    | Azure repo or Confluence | Decide                                                |
+| Process docs and ways of working                                 | Confluence               | Likely yes                                            |
+| Meeting notes and retro outputs                                  | Confluence               | Likely yes                                            |
+| Polished artifacts for wider org                                 | SharePoint               | Likely yes                                            |
+| "The forge"                                                      | Unknown                  | Must identify: what is it and what role does it play? |
+
+Rule: if a document needs to be AI-readable, it lives in the repo. If it is human-only reference, Confluence or SharePoint.
+
+**On Architecture Decision Records (ADRs)**
+
+An ADR is a short document that records a hard-to-reverse decision: what we decided, what alternatives we considered, and why. The value is not the document itself — it is that six months from now, when someone asks "why did we do it this way?", the answer is written down and findable.
+
+ADRs are written *after* a decision is made, not before. They live in the repo alongside the code they affect (e.g. `docs/adr/0001-branching-strategy.md`). They are never updated — if a decision changes, a new ADR supersedes the old one.
+
+Decisions worth recording as ADRs: branching strategy, commit convention, global vs local config structure, AI constitution scope, skills library ownership model.
+
+*Issues to generate:*
+- "Define and document content-type-to-location mapping"
+- "Set up Confluence space structure"
+- "Identify what 'the forge' is and whether it has a role in our docs structure"
+- "Write ADRs for decisions made in this session"
+
+---
+
+### 7. Session close: identify follow-up grill sessions (15 min)
+
+For each topic not resolved in the session, scope a follow-up grill:
+
+```
+Topic: [what needs to be resolved]
+Why it is blocked: [what cannot move forward until this is decided]
+Who needs to be in the room: [roles, not names]
+Rough timebox: [30 min / 1 hour / half day]
+```
+
+Likely follow-up topics:
+- Custom agents / Copilot Extensions evaluation
+- Skills library design (versioning, contribution model, org adoption path)
+- Scope definition (if not resolved in block 2)
+- Documentation structure detail (if the forge question is unresolved)
+- Prompting standards and shared prompt library
+
+---
+
+## Open questions the session must resolve
+
+| Question                                                           | Why it matters                                                       |
+| --------------------------------------------------------------------| ----------------------------------------------------------------------|
+| What goes into `copilot-instructions.md`?                          | Determines AI output quality baseline for everyone                   |
+| What context files do we commit to every repo?                     | Without this, AI agents cannot navigate our codebases                |
+| What is our branching and commit convention?                       | Shapes every PR, review, and history going forward                   |
+| What code review standard applies to AI-generated code?            | Without this, quality is undefined                                   |
+| What is our workstream model?                                      | Without a shared pattern, every piece of work is handled differently |
+| Do enterprise AI policies exist that constrain our constitution?   | Our rules must align with — not contradict — existing policy         |
+| Do we start with a shared team repo (global) or per-project first? | Every other config decision depends on this architecture choice      |
+| What is our documentation structure?                               | Without this, knowledge scatters immediately                         |
+| What is "the forge" and what role does it play?                    | Cannot finalise docs structure without this                          |
+
+---
+
+## Appendix: an approach worth knowing about
+
+The patterns described in this brief — context files, skills libraries, provider adapters, AI constitutions — are not invented from scratch. There is a coherent architectural approach behind them, worth understanding as a team before you decide how to implement your own version.
+
+### The core idea
+
+Think of AI collaboration config as a layered system with a clear separation of concerns:
+
+- **A provider-agnostic core** — your conventions, principles, domain language, and team agreements written in plain language, with no references to specific tools. This content is stable: it does not change when you switch from Copilot to another tool, or when Copilot changes its format.
+- **Thin provider adapters** — tool-specific files (`copilot-instructions.md`, VS Code settings, CLI config) that translate your core content into the format each tool expects. These change when tools change; your core does not.
+- **Two tiers of context** — not everything should be loaded all the time. A short always-loaded file (your `copilot-instructions.md`) contains universal rules and pointers. Deeper content (domain language, architecture decisions, specific conventions) lives in separate files the AI reads on demand. This keeps context lean and relevant.
+
+The implication: write your conventions once in plain language, then adapt them per tool. Do not write them once per tool.
+
+### Content as distinct primitives
+
+Treat each type of AI-collaboration content as its own thing:
+
+- **Instructions** — stateless rules that define how AI should behave (coding style, communication tone, what to avoid)
+- **Skills** — reusable slash commands for specific tasks (write a PR description, generate a test, summarise a diff); the most portable primitive across tools
+- **Workflows** — chains of skills for multi-step tasks (grill a design → draft a spec → break into issues)
+- **Agents** — role definitions that give AI a specific perspective for a task (reviewer, architect, developer)
+- **Prompts** — shared fragments embedded in multiple skills or workflows
+
+Starting with skills is the right move. They are immediately useful, easy to share, and work across GitHub Copilot, Claude Code, Cursor, and others via the Agent Skills open standard (`.agents/skills/` directory, `SKILL.md` format).
+
+### Global versus local
+
+This is the most important architectural decision you will make. There are two levels:
+
+**Global (team-level, shared across all projects)**
+A shared repo or config location that holds your team's baseline: core instructions, shared skills library, universal AI constitution, provider adapter templates. Every project inherits from this. When you update a convention here, all projects can pull it in.
+
+This is what a centre of excellence maintains. It is the artefact that makes you reusable beyond your own team.
+
+**Local (per-project)**
+Each project repo holds what is specific to it: a `CONTEXT.md` with that project's domain language, project-level overrides to the shared instructions, and project-specific skills. Local config extends the global baseline — it does not replace it.
+
+The rule: if a convention applies to all your projects, it belongs in the global layer. If it is specific to one project's domain or stack, it belongs local.
+
+Starting point for a small team: begin with everything local, one repo at a time. Extract to a global layer once you see the same content appearing in multiple projects. Do not over-engineer the global layer before you know what belongs in it.
+
+### What grows into what
+
+A team that gets this right ends up with:
+- A shared team repo (the global layer) that any new project can pull from
+- Per-project context files that are thin, focused, and AI-readable
+- A skills library that grows incrementally as the team identifies recurring tasks worth automating
+- An AI constitution that evolves with each sprint retro
+
+That shared team repo — the global layer — is the seed of a CoE artefact. It is also the thing that makes onboarding a new team member (or a new AI agent) fast: point them at the global repo and they have your conventions, your domain language, and your working agreements in one place.
+
+### Things to decide as a team
+
+Before you start building, align on:
+- Do we start with a shared team repo now, or per-project first and extract later?
+- Who owns the global layer and how do we propose changes to it?
+- How do projects pull updates from the global layer — manual copy, sync script, or something else?
+- What is our policy on AI agents modifying context files directly vs. humans only?