From ab367a48c461da43a739e1c9f83f2eeba09ecc98 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sun, 10 May 2026 20:19:39 +0000 Subject: [PATCH] docs: governance workstream exploration and context consolidation --- CLAUDE.md | 4 + CONTEXT.md | 8 + docs/ROADMAP.md | 5 +- docs/notes/ai-ethics-security-principles.md | 89 +++++ .../team-self-organisation-sprint-brief.md | 378 ++++++++++++++++++ 5 files changed, 482 insertions(+), 2 deletions(-) create mode 100644 docs/notes/ai-ethics-security-principles.md create mode 100644 docs/notes/team-self-organisation-sprint-brief.md diff --git a/CLAUDE.md b/CLAUDE.md index ab4b614..bc59e36 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -40,3 +40,7 @@ Each chunk follows this sequence: 6. Start a new session before the next chunk Don't skip `/tdd` — it's the easy one to forget. + +## Working context + +This repo is built by a junior developer as a homelab tool intended to scale to professional environments. Challenge ideas and reference industry standards rather than validate assumptions. Explain the why behind decisions — assume the user is learning, not just executing. Flag significant actions before taking them. diff --git a/CONTEXT.md b/CONTEXT.md index c00c625..2325459 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -36,6 +36,8 @@ Workflow artifacts are committed to `docs/` in subdirectories by type. All are t ### Content chunk QA Instruction files and other content chunks cannot be unit tested. Verification is human-executed after implementation: open a new Claude session, exercise the relevant behaviour, and confirm the rules take effect. Each issue includes a short acceptance criteria checklist for the human to run post-commit. Automated QA applies to tooling (scripts, hooks); manual QA applies to agent behaviour and content correctness. +**Instruction quality matters more than instruction presence.** In-context rules (including always-on CLAUDE.md rules) compete with the model's RLHF-trained defaults and can lose — even in a fresh session with the files correctly deployed. Flat one-liner imperatives are the weakest form. Rules that are specific, include a counter-example ("do X, not Y"), or show the boundary condition are significantly more reliable. When a behavioral test fails, the first question is whether the rule is underspecified, not whether in-context instruction-following is inherently unreliable. Do not accept rule violations as an expected baseline — treat them as a signal to strengthen the instruction. + ### Conventional commits All commits in this repo follow the Conventional Commits specification (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`). Convention is defined in `core/instructions/git.md`. Changelog tooling is a follow-on issue — convention is established first. @@ -45,6 +47,12 @@ Projects override on-demand content (workflows, agent roles, prompts) by placing ### Sync model Projects must never edit synced files directly — customizations live in separate override files. A sync conflict is a signal that a synced file was edited directly. +### Repo as source of truth +All project state, decisions, context, and working conventions live in this repo. External memory systems should not be used for this project — they create a split-brain risk where cached state diverges from the repo. At the start of every session, read `CLAUDE.md`, `CONTEXT.md`, and `docs/VISION.md`. Everything needed to orient is here. + +### Working context +This repo is built by a junior developer as a homelab tool intended to scale to professional environments. The agent should challenge ideas and reference industry standards rather than validate assumptions. Explain the why behind decisions — assume the user is learning, not just executing. Flag significant actions before taking them. + ## Glossary ### Management Application diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 9fe69d4..2eb75ce 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -16,7 +16,7 @@ Chunk 6 (tooling) is exempt — it is implementation-driven, not content-driven. | Chunk | Scope | Why this order | |---|---|---| | ✅ 1 | Repo skeleton + `install.sh` — structure in place, Claude Code wired up | Nothing else can be built without the structure and install working | -| ✅ 2 | Core instructions — `coding.md`, `git.md` (incl. conventional commits), `testing.md`; communication rules in `providers/claude-code/CLAUDE.md` always-on section; retire `global.md`; migrate `docs/` to subdirectory-by-type naming | Instructions are the foundation everything else references; commit convention and doc naming must be in place before history accumulates | +| ⏳ 2 | Core instructions — `coding.md`, `git.md` (incl. conventional commits), `testing.md`; communication rules in `providers/claude-code/CLAUDE.md` always-on section; retire `global.md`; migrate `docs/` to subdirectory-by-type naming | Instructions are the foundation everything else references; commit convention and doc naming must be in place before history accumulates | | 3 | First skills — initial slash commands for day-to-day use; changelog tooling (follow-on to Chunk 2 conventional commits); catalogue existing skills incl. `zoom-out` which is installed but undocumented | Skills are the most immediately useful output; validates the full pipeline | | 4 | Workflows — formalize the workstream workflow (kick-off types → grill → artifact → issues → implement → QA → commit); feature, bug, architecture, improvement, feedback patterns | Higher-level patterns built on top of a working skills foundation; grill feedback intake design before starting | | 5 | Agents — role definitions (reviewer, architect, developer) | More abstract definitions; benefits from workflow patterns being established first | @@ -68,8 +68,9 @@ Items consciously not resolved — to be addressed in the relevant chunk PRD or | Changelog tooling — which generator (git-cliff, conventional-changelog, etc.) and where it runs | Chunk 3 grill | | Content index frontmatter — replace inline `when:` hints in CLAUDE.md content index with a `when:` field in each instruction/skill file so the agent discovers load conditions from the file itself. Cover before implementing Chunk 3 skills. | Chunk 3 grill | | Agent behavior confirmation model — writes/edits/git currently require stating intent + approval before acting. Loosen to autonomy-first once skills and workflows are proven and automated agents replace direct interaction. | Phase 2 refinement (post Chunk 4) | -| CLAUDE.md always-on refinement — security floor (no credentials/auth URLs), scope discipline (no over-engineering), tool preference (Read/Edit over Bash). Needs its own grill session → PRD before implementation. | Future workstream, post Chunk 2 | +| CLAUDE.md always-on refinement — security floor (no credentials/auth URLs), scope discipline (no over-engineering), tool preference (Read/Edit over Bash); **plus instruction quality**: current rules are thin one-liners observed in practice to lose to RLHF-trained defaults (verbose responses, validating user positions); fix is specificity, counter-examples, and boundary framing — not accepting violations as expected. Needs its own grill session → PRD before implementation. | Future workstream, post Chunk 2 | ## Housekeeping reminders - **`.gitkeep` files** — placeholder files exist in `core/agents/`, `core/workflows/`, `core/prompts/`, `docs/ard/`, `docs/bug/`, `docs/notes/`. Remove each when the first real file is added to that directory. Each `.gitkeep` names the chunk that will populate it. +- **Chunk 2 behavioral tests** — 8 manual scenarios in `tests/test-chunk2.sh` (MANUAL TEST PLAN section) are pending verification. Must run in a fresh Claude session before Chunk 2 is fully verified. See instruction quality finding in `CONTEXT.md` for why these cannot be skipped. diff --git a/docs/notes/ai-ethics-security-principles.md b/docs/notes/ai-ethics-security-principles.md new file mode 100644 index 0000000..4f5c28a --- /dev/null +++ b/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/.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. +``` diff --git a/docs/notes/team-self-organisation-sprint-brief.md b/docs/notes/team-self-organisation-sprint-brief.md new file mode 100644 index 0000000..c40d012 --- /dev/null +++ b/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.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?