sw-team-scrum-master

name

sw-team-scrum-master

description

Agentic SCRUM Master workflow for SW-TEAM framework development: sprint state persistence, backlog management across five deliverable types ({package}/ code, spec templates, SKILL.md files, .agent.md files, integration artefacts), dual-track QA coordination (Code QA for Python, Agent QA for agentic deliverables), design-brief gating, cross-phase dependency enforcement, and SCRUM ceremonies adapted for agentic framework development. Use when managing dev-phase progress, planning phases, checking exit criteria, tracking blockers, running retrospectives, coordinating handoffs between Architect/Implementer/Code QA/ Agent QA, or maintaining project health dashboards across sessions — even if "SCRUM" is not mentioned explicitly.

SW-TEAM Agentic SCRUM Master Skill

This skill defines best practices, workflows, and artefact conventions for an AI agent acting as SCRUM Master / Project Manager for SW-TEAM framework development. It extends the standard agentic SCRUM workflow with five deliverable types and dual-track QA specific to building an agentic framework (not just a Python library).

---

FIXED — Universal SW-TEAM SCRUM Procedures

The sections below apply to any SW-TEAM framework build, regardless of domain. Do NOT modify these sections for a new domain — only the ADAPT section below should be customised.

---

1. Persistent Sprint State

Why it matters

An AI agent has no memory across sessions by default. Without a persistent state file, the SCRUM Master must re-discover phase status from scratch on every invocation — expensive and error-prone.

Convention

Maintain a sprint state file at:

.github/context/sw-team-scrum-master/sprint_state.md

This file is the single source of truth for current dev-phase status. It is read at the start of every session and updated at the end of every action that changes phase state.

Sprint State File Structure

See ./templates/sprint_state.md for the full template. Key sections:

Section	Purpose
## Current Dev Phase	ID, name, state, dates
## Design Brief	Architect design gate status per deliverable type
## Backlog Status	One row per deliverable with type, status, QA track
## Exit Criteria	Checklist — gating criteria from the framework doc deliverables section (read from domain-context SKILL)
## QA Status	Code QA and Agent QA results tracked separately
## Impediments	Open blockers with owner and age
## Deferred Items	v2+ items with clean-check status
## Velocity Log	Historical: deliverables completed per phase
## Decision Log	Key decisions made this phase

Update Rules

• Read sprint_state.md at the start of every session before making any statement about project status.
• Write sprint_state.md after any status change: deliverable completed, blocker added, exit criterion checked, design gate passed, QA result received, decision made.
• Never report a status from memory — always read from the file.

---

2. Issue Tracking Setup

Option A — GitHub Issues (preferred when available)

When a GitHub remote is configured, use GitHub issues as the canonical tracker:

• Each deliverable maps to one GitHub issue with labels: backlog, in-progress, blocked, done + type label: type:package, type:spec, type:skill, type:agent, type:integration
• Each dev phase is a GitHub Milestone. Phase IDs come from the domain-context SKILL (§FIXED — Dev phase list).
• Blockers get a blocked label and a comment explaining the dependency.
• Deferred items get a deferred-v2 label.
• QA results are recorded as issue comments with code-qa:pass/fail or agent-qa:pass/fail labels.

Workflow:

1. At phase planning: create issues for all deliverables; assign to milestone.
2. At check-in: update labels as work progresses.
3. At QA: add QA result label; close issue when both applicable QA tracks pass.
4. Mirror all status in sprint_state.md (the file is the offline cache).

Option B — Document-only tracking

When GitHub issues are not used, sprint_state.md is the only tracker:

• Each deliverable has a unique ID (e.g., {phase-id}-07) matching the framework doc's dev phase deliverables section (read from domain-context SKILL §FIXED — Dev phase list).
• Status symbols: ✅ complete | 🔄 in progress | ❌ not started | 🚫 blocked
• Add a last_updated timestamp to each row when status changes.
• At phase planning, copy deliverables from the framework doc deliverables section into the backlog.

Hybrid (recommended)

Use GitHub issues for visibility + sprint_state.md as the offline cache.

---

3. SCRUM Ceremonies (Adapted for SW-TEAM Framework)

3.1 Dev Phase Planning

Trigger: User asks to plan the next phase, or prior phase exits.

Steps:

1. Read sprint_state.md. Confirm prior phase is DONE.
2. Load domain-context SKILL to read the phase list and per-phase design brief contents (e.g., #tool:read_file → .github/skills/{domain}-builder-context/SKILL.md). Read §FIXED — Dev phase list and §FIXED — Per-phase design brief contents.
3. Read the framework doc deliverables section (path from domain-context SKILL §ADAPT — Framework document) for the next phase's deliverables and validation test.
4. Check dependencies using the cross-phase dependency map from the domain-context SKILL (§FIXED — Cross-phase dependencies). If any hard dependency is unmet, the phase is BLOCKED — report and stop.
5. Verify the design brief is either already produced or is the first item to hand off to the Architect.
6. Create the phase branch:

   git checkout develop
   git pull origin develop
   git checkout -b dp-N/<slug>
   

   Confirm with git branch --show-current.
7. Write the new phase section to sprint_state.md:
   • Set state to DESIGN (if design brief is pending) or IN PROGRESS
   • Populate backlog table with all deliverables from the framework doc deliverables section (all as ❌)
   • Set design brief status per deliverable type (applicable / N/A)
   • Populate exit criteria from the framework doc validation test (all unchecked)
   • Set both QA tracks to NOT RUN
8. If using GitHub: create milestone and issues.
9. Hand off to Architect for the design brief.
10. Report the plan to the user in the standard phase status format.

Output: Updated sprint_state.md + phase status report.

3.2 Daily / Async Status Check

Trigger: User asks "What's the status?" or "What's blocking us?"

Steps:

1. Read sprint_state.md.
2. For each in-progress deliverable (🔄), verify whether the artefact now exists:
   • {package}/ code: #tool:file_search for the module path
   • Spec templates: #tool:file_search in templates/
   • SKILL.md: #tool:file_search in .github/skills/
   • .agent.md: #tool:file_search in .github/agents/
   • Integration: #tool:file_search for copilot-instructions.md or kb/*.md
3. For each blocked item (🚫), check if the blocker has been resolved.
4. Report: what moved forward, what is still blocked, what is done.
5. Update sprint_state.md with any new completions or unblocks.

Output: Status snapshot (current phase only). Keep to 10 lines unless detail is requested.

3.3 Exit Criteria Verification

Trigger: Implementer signals all deliverables complete, or agent detects all items are ✅.

This is a two-track process. The SCRUM Master does NOT verify exit criteria directly — it coordinates the two QA agents.

Steps:

1. Read the phase's validation test from the framework doc deliverables section (path from domain-context SKILL §ADAPT — Framework document).

2. Classify each validation criterion by QA track:

   Criterion type	QA track	Verification method
   {package}/ function exists and is importable	Code QA	pytest, ruff, mypy
   {package}/ function produces correct output	Code QA	Unit test against domain validation scenario fixtures
   Coverage ≥ threshold on {package}/ modules	Code QA	pytest --cov
   Spec template has all required fields	Agent QA	Field checklist from the framework doc spec inventory (read from domain-context SKILL)
   SKILL.md has valid FIXED/ADAPT sections	Agent QA	Contract validation
   SKILL.md Layer A references resolve	Agent QA	Cross-ref against {package}/
   .agent.md frontmatter parses correctly	Agent QA	Syntax check
   .agent.md handoffs are self-contained	Agent QA	Prompt completeness review
   Integration test (domain validation scenario) passes	Agent QA	End-to-end scenario check

3. Hand off to Code QA using the "Request code QA" handoff.

4. Hand off to Agent QA using the "Request agent QA" handoff.

5. Wait for both QA reports.

6. For each criterion, match it to the relevant QA report and mark ✅ or ❌.

7. If all criteria are ✅ on both tracks:

   • Set phase state to DONE
   • Record completion date
   • Update velocity log
   • Trigger phase planning for the next phase (§3.1)

8. If any criterion is ❌:

   • Report which criteria are unmet and which QA track flagged them
   • Hand off to Implementer with the specific failure and file path
   • After rework, re-invoke only the QA track that failed
   • Do not advance the phase

Output: Exit criteria checklist with pass/fail per item + QA track + overall PASS/FAIL.

3.4 Sprint Review

Trigger: Phase is DONE; user wants a summary.

Steps:

1. Read sprint_state.md for the completed phase.
2. List all artefacts delivered, grouped by deliverable type:
   • {package}/ functions delivered (with module paths)
   • Spec templates delivered
   • SKILL.md files delivered
   • .agent.md files delivered (if any)
   • Integration artefacts delivered (if any)
3. Summarise what changed since the prior phase (#tool:search/changes).
4. List any items deferred and their target version.
5. Report metrics: deliverables planned, completed, deferred — by type.
6. Run multi-track consistency check (§4b) if the phase involved track-specific deliverables (per domain-context SKILL §FIXED — Modelling tracks).

Output: Markdown summary + decision log update.

3.5 Sprint Retrospective

Trigger: Sprint review is complete. User asks for retrospective.

Steps:

1. Read sprint_state.md (impediment log, decision log, velocity log).
2. For each impediment resolved this phase: record what worked.
3. For each impediment that persisted: record what to improve.
4. Specifically review:
   • Did the design brief have enough detail for the Implementer?
   • Did the dual QA track cause unnecessary rework loops?
   • Were FIXED/ADAPT boundaries clear in SKILL.md deliverables?
   • Did any {package}/ API change break an existing SKILL.md's Layer A references?
5. Propose at most 3 process improvements for the next phase.
6. Append retrospective to .github/context/sw-team-scrum-master/retrospectives.md (create from ./templates/retrospectives.md if absent).

Output: Retrospective notes file updated.

---

4. Dependency and Consistency Management

4a. Cross-Phase Dependencies

The cross-phase dependency map is domain-specific. Read it from the domain-context SKILL loaded at session startup (e.g., {domain}-builder-context/SKILL.md §FIXED — Cross-phase dependencies).

Generic rule: before opening a new phase, verify that all hard dependencies listed in the domain-context SKILL are met. If any is unmet: add to impediment list, set phase BLOCKED.

4b. Multi-Track Consistency Check

Some domains support multiple modelling tracks with strict isolation rules (no cross-track imports, no shared wrappers). The track list and per-track rules are domain-specific. Read from the domain-context SKILL (e.g., {domain}-builder-context/SKILL.md §FIXED — Modelling tracks).

Run a consistency check after any phase that adds or modifies track-specific deliverables. Any cross-track contamination is a P0 blocker — flag immediately.

---

5. Impediment Management

What counts as an impediment

• A design brief section is missing before implementation begins
• A hard dependency on a prior phase is not resolved
• A Code QA failure blocks a downstream SKILL.md (Layer A reference broken)
• An Agent QA failure on a SKILL.md reveals a missing {package}/ function
• A cross-track consistency violation is detected
• A deferred item reference appears in a v1 deliverable

Impediment lifecycle

1. Open: Add to sprint_state.md impediment table with date, description, owner, and which QA track (if any) surfaced it.
2. Escalate: If unresolved for > 1 session, escalate in the status report.
3. Resolve: When resolved, mark with resolution date and brief note.
4. Archive: Move to decision log at sprint review.

Impediment record format

| ID | Description | Owner | Opened | QA track | Status | Resolution |
|----|-------------|-------|--------|----------|--------|------------|
| IMP-01 | {package}.utils.manifest.append_artefact() missing | Implementer | YYYY-MM-DD | Code QA | 🔴 Open | — |
| IMP-02 | ingest-data SKILL.md refs non-existent function | Implementer | YYYY-MM-DD | Agent QA | 🔴 Open | — |

---

6. Velocity Tracking

Track completed deliverables per phase, broken down by type.

Update the velocity log in sprint_state.md at the end of each phase:

| Phase       | {pkg}/ | spec | skill | agent | integ | Total | Planned | Velocity |
|-------------|--------|------|-------|-------|-------|-------|---------|----------|
| {phase-id-1}| 1      | 0    | 0     | 1     | 4     | 6     | 6       | 100%     |
| {phase-id-2}| 2      | 0    | 1     | 1     | 0     | 4     | 4       | 100%     |

---

7. Deferral Management

Deferred items are domain-specific. Read the deferral register from the domain-context SKILL (e.g., {domain}-builder-context/SKILL.md §FIXED — Deferral register).

Verification cadence: at the start of every new phase, confirm no deliverable references a deferred item. Use #tool:search/textSearch for the deferred item names listed in the domain-context SKILL. Any hit in {package}/ or .github/skills/ is a P0 blocker.

---

8. Standard Reporting Formats

Phase Status Report

## Dev Phase DP-N — [Name] — [STATE] — [DATE]

### Design Brief (Architect)
- ✅/❌ {package}/ function signatures — <defined/missing/N/A>
- ✅/❌ Spec template structure — <defined/missing/N/A>
- ✅/❌ SKILL.md scaffold layout — <defined/missing/N/A>
- ✅/❌ .agent.md prompt architecture — <defined/missing/N/A>

### Backlog
| Item     | Type  | Description | Status    | Path             | QA track |
|----------|-------|-------------|-----------|------------------|----------|
| DP-N-01  | pkg   | ...         | ✅/🔄/❌/🚫 | {package}/...    | Code     |
| DP-N-02  | skill | ...         | ✅/🔄/❌/🚫 | .github/skills/… | Agent    |
| DP-N-03  | spec  | ...         | ✅/🔄/❌/🚫 | templates/…      | Agent    |

### Code QA ({package}/ functions)
- Status: PASS / FAIL / NOT RUN
- Tests: N/M passing
- Coverage: N%
- Lint: clean / N issues

### Agent QA (agentic deliverables)
- Status: PASS / FAIL / NOT RUN
- Spec templates: N/N validated
- SKILL.md files: N/N validated (FIXED/ADAPT + Layer A refs)
- .agent.md files: N/N validated
- Integration test: PASS / FAIL / NOT RUN

### Exit Criteria (from domain-context SKILL phase list)
- ✅/❌ <criterion>

### Impediments
- 🔴/🟡 <description> — Owner: <n> — QA track: <Code/Agent>

### Velocity: N/M deliverables complete (V%)

### Next Action
<action and responsible agent>

Health Dashboard (all phases)

## SW-TEAM Framework — Health Dashboard — [DATE]

| Phase | Name              | State       | pkg/  | spec | skill | agent | integ | Blockers |
|-------|-------------------|-------------|-------|------|-------|-------|-------|----------|
| P0           | Prerequisites     | ✅ DONE     | 1/1   | 0/0  | 0/0   | 1/1   | 4/4   | 0        |
| {phase-id-1} | {phase-name-1}    | 🔄 IN PROG  | 0/0   | 0/1  | 0/0   | 0/0   | 1/3   | 0        |
| {phase-id-2} | {phase-name-2}    | ❌ NOT START| 0/2   | 0/0  | 0/1   | 0/1   | 0/0   | 0        |
| ...          |                   |             |       |      |       |       |       |          |

Active: {phase-id-1} — {phase-name-1}
Code QA: NOT RUN | Agent QA: NOT RUN
Blockers: None
Next milestone: {phase-id-1} closure → {phase-id-2} design brief

Retrospective Format

Appended to .github/context/sw-team-scrum-master/retrospectives.md:

## Retrospective — DP-N: [Phase Name] — YYYY-MM-DD

### What went well
-

### What to improve
-

### SW-TEAM-specific observations
- Design brief adequacy: <sufficient / gaps in ...>
- Dual QA efficiency: <smooth / rework loops in ...>
- FIXED/ADAPT clarity: <clear / ambiguous in ...>
- Layer A cross-ref: <no breaks / broke in ...>

### Action items for next phase (max 3)
1.
2.
3.

### Metrics
- Deliverables planned: N ({package}/: N, spec: N, skill: N, agent: N, integ: N)
- Deliverables completed: N
- Deliverables deferred: N
- Impediments opened: N
- Impediments resolved: N
- Velocity: N%
- Code QA runs: N (pass: N, fail: N)
- Agent QA runs: N (pass: N, fail: N)

---

ADAPT — Domain Configuration

The following values are domain-specific. Read them from the domain-context SKILL at session startup. Do NOT hardcode them here.

Value	Source in domain-context SKILL
Framework doc path	§FIXED — Framework Document — the path: field
Dev phase deliverables section	§FIXED — Framework Document — the dev phase / deliverables section
Domain validation scenario	§FIXED — Validation Scenario
Dev phase list	§FIXED — Dev phase list
Deferral register	§FIXED — Deferral register

Agent instruction: At session startup, read the domain-context SKILL and substitute these values wherever this SKILL references {framework_doc_path}, {domain}, or {phase_list}.