Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

docs: governance workstream exploration and context consolidation

Browse Source
This commit is contained in:
Defame1297
2026-05-10 20:19:39 +00:00
parent a3bb708bff
commit ab367a48c4
5 changed files with 482 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

378
docs/notes/team-self-organisation-sprint-brief.md Normal file
View File

@@ -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?