Awesome/awesome-copilot
1
0
Fork 0
mirror of https://github.com/github/awesome-copilot.git synced 2026-08-01 23:12:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Simplify AI Team Orchestration workflow 🤖 (#2439)

Browse Source 
* Simplify AI Team Orchestration workflow

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Clarify recovery context sources

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
denis-a-evdokimov
2026-07-30 03:49:48 +02:00
committed by GitHub
parent 0648d53070
commit 7968055c17
14 changed files with 295 additions and 612 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/ai-team-orchestration/SKILL.md
+58 -114
View File
@@ -1,148 +1,92 @@
---
name: ai-team-orchestration
description: 'Bootstrap and run a multi-agent AI development team. Use when: starting a new software project with AI agents, setting up parallel dev/QA teams, creating sprint plans, writing brainstorm prompts with distinct agent voices, recovering a project workflow, or planning sprints.'
description: 'Bootstrap and run a lightweight multi-agent development team. Use when starting or adopting a project, planning work, coordinating implementation and optional QA, brainstorming with distinct perspectives, or preserving context across sessions.'
---
# AI Team Orchestration
## When to Use
- Starting a new project that needs planning, development, testing, and deployment
- Setting up parallel AI agent teams (dev, QA, DevOps)
- Writing brainstorm prompts that produce real debate (not generic output)
- Creating sprint plans with cross-chat context survival
- Recovering from context overflow mid-sprint
Use three stable agents:
## Team Roles
| Agent | Purpose |
|---|---|
| `@ai-team-producer` | Clarify scope, plan proportionately, coordinate, and merge |
| `@ai-team-dev` | Implement, test, self-review, and prepare the pull request |
| `@ai-team-qa` | Independently test behavior when dedicated QA is useful |
| Agent | Name | Role | Focus |
|-------|------|------|-------|
| Producer | **Remy** | Sprint planning, coordination, merging PRs | Scope control, handoffs, issue triage |
| Product Designer | **Kira** | UX, mechanics, user experience | Fun factor, user flows, feature design |
| Visual/Art Director | **Milo** | CSS, animations, visual identity | Design system, polish, accessibility |
| Frontend Engineer | **Nova** | UI framework, state management, components | React/Vue/Svelte, client-side logic |
| Backend Engineer | **Sage** | API, database, auth, security | Server-side logic, infrastructure |
| DevOps Engineer | **Dash** | CI/CD, cloud deployment, pipelines | GitHub Actions, Azure/AWS/GCP |
| QA Engineer | **Ivy** | E2E tests, automation, playtesting | Playwright/Cypress, bug filing, sign-off |
Nova, Sage, and Milo are perspectives inside the Dev agent, not mandatory project layers.
Customize names and roles for your project. Not every project needs all roles.
## Default Workflow
## Chat Architecture
**Plan -> Implement -> Test -> optional review or QA -> Merge -> update project state**
The human (CEO) is the message bus between parallel chats:
Keep the workflow proportional:
```
┌────────────────────────────────────────┐
│ @ai-team-producer — Plans, merges │
│ NEVER writes code │
└────────────────┬───────────────────────┘
│ Human carries messages
┌──────────┼──────────┐
▼ ▼ ▼
┌──────────┐ ┌────────┐ ┌────────┐
│@ai-team │ │@ai-team│ │DevOps │
│-dev │ │-qa │ │(on │
│ │ │ │ │demand) │
│ Nova │ │ Ivy │ │ │
│ Sage │ │ │ │ │
│ Milo │ │ │ │ │
│ │ │feature/│ │feature/│
│ feature/ │ │qa-N │ │devops-N│
│ sprint-N │ └────────┘ └────────┘
└──────────┘
```
- Skip formal planning for small, obvious changes.
- Use a short plan for multi-step or cross-cutting work.
- Add independent review or QA when risk, uncertainty, or repository policy justifies it.
- Let branch protection, required checks, permissions, and merge queues enforce repository merge policy.
Each team works in a **separate VS Code window** with its own clone:
```bash
git clone <repo> project-dev # Dev team
git clone <repo> project-qa # QA
git clone <repo> project-devops # DevOps (only when needed)
```
## Start or Adopt a Project
## Project Bootstrap
1. Read existing repository instructions and documentation.
2. Discover the actual stack, architecture, commands, deployment model, and risks.
3. Create or update `PROJECT_BRIEF.md` only when durable cross-session context is useful. Start from the [project brief template](./references/project-brief-template.md) and omit irrelevant sections.
4. For substantial work, create a concise plan from the [sprint plan template](./references/sprint-plan-template.md).
5. Use a separate branch or clone when parallel sessions could conflict, following the repository's own Git policy.
### 1. Create PROJECT_BRIEF.md
## Execute
The single source of truth across all chats. See the [project brief template](./references/project-brief-template.md).
### Producer
**Required sections (do not abbreviate):**
1. Project Overview
2. Concept / Product Description
3. Tech Stack
4. Architecture (ASCII diagram)
5. Key Files Map
6. Team Roles
7. Sprint Status (updated every sprint)
8. Current State (rewritten every sprint)
9. Security Rules
10. How to Run Locally
11. How to Deploy
12. **Cross-Chat Handoff Protocol** — how context survives between chats
13. **Bug & Fix Tracking** — GitHub Issues as single source of truth
14. **Multi-Repo Setup** — separate clones, branch strategy, merge rules
- Define the outcome, constraints, acceptance criteria, and explicit exclusions.
- Choose review and QA based on risk rather than ceremony.
- Keep durable project state concise and current.
### 2. Run a Brainstorm
### Dev
See the [brainstorm format](./references/brainstorm-format.md). Key: name each agent explicitly with distinct personality and perspective. Require at least 2 genuine disagreements to prevent groupthink.
- Follow repository conventions and implement the smallest complete solution.
- Run relevant checks and inspect the final diff.
- Open or update the pull request with summary, verification, and limitations.
### 3. Create Sprint Plans
### QA
See the [sprint plan template](./references/sprint-plan-template.md). Every sprint gets:
- `docs/sprint-N/plan.md` — prioritized tasks, success criteria
- `docs/sprint-N/progress.md` — live tracker, enables recovery
- `docs/sprint-N/done.md` — handoff doc written at sprint end
- Use only when dedicated behavioral verification adds value.
- Test the requested change and important regressions.
- Report reproducible findings and verify fixes.
### 4. Execute Sprints
## Brainstorms
```
Read PROJECT_BRIEF.md, then read docs/sprint-N/plan.md. Execute Sprint N.
First: git pull origin main && git checkout -b feature/sprint-N
Close GitHub Issues in commits: "fix: description (Fixes #NN)"
Update docs/sprint-N/progress.md after each phase.
When done, push and create PR: git push origin feature/sprint-N
Follow Sections 12-14 of PROJECT_BRIEF.md.
```
### 5. QA Sign-off
After dev merges, QA does a full playthrough:
```
Read PROJECT_BRIEF.md. You are Ivy (QA).
Sprint N is merged to main. Do full playthrough.
File bugs as GitHub Issues. Write docs/qa/sprint-N-signoff.md.
```
Use the [brainstorm format](./references/brainstorm-format.md) for product or architecture decisions that benefit from competing perspectives. For ordinary implementation choices, let Dev decide using repository conventions.
## Context Recovery
When a chat gets long (>100 messages), save state and start fresh:
Before ending a long or interrupted session:
**Before closing:**
1. Update `docs/sprint-N/progress.md` with current status
2. Update `PROJECT_BRIEF.md` sections 7+8
3. Write `docs/sprint-N/done.md`
1. Update the active plan or progress note if one exists.
2. Record material decisions, blockers, and the next action in repository context.
3. Use a cold-start prompt such as:
**Cold start prompt:**
```
Read PROJECT_BRIEF.md and docs/sprint-N/progress.md.
Continue from where it left off.
```text
Read the repository instructions, then read whichever sources exist for this
work: the active issue or request, PROJECT_BRIEF.md, and the active plan or
progress note.
Continue from the recorded next action.
```
## Anti-Patterns
## Tool and Model Inheritance
See [anti-patterns reference](./references/anti-patterns.md) for the full list. Top 5:
The bundled agents intentionally omit `tools` and `model` frontmatter:
| Don't | Do Instead |
|-------|------------|
| Rebase feature branches | Merge (rebase loses commits) |
| Producer writes code | Producer only plans, merges, files issues |
| Batch "fix everything" commits | One commit per fix with issue reference |
| Vague brainstorm prompts | Name each agent with distinct perspective |
| Keep bugs only in chat | File GitHub Issues (chat context dies) |
- available built-in, MCP, and extension tools remain usable;
- developers keep control of model selection;
- role boundaries are defined by instructions and normal trust, permission, authentication, and approval controls.
## Tips for Better Results
If the environment exposes too many tools, deselect irrelevant tools or MCP servers, or use VS Code virtual-tool management. Do not add a machine-specific plugin allowlist.
- **"Take your time, do it right"** in prompts produces better output than rushing
- **Test before merge** — you playtest, file issues, dev fixes, then merge
- **Run team consiliums** before major sprints — each agent reviews the plan from their perspective
- **Save lessons to memory** after every milestone
## Principles
- Prefer working software and clear handoffs over process artifacts.
- Follow repository policy instead of embedding universal Git commands.
- Preserve unknown work and ask before destructive or privileged actions.
- Keep bugs and important decisions in durable project systems, not only chat.
- See [anti-patterns](./references/anti-patterns.md) for concise lessons.
skills/ai-team-orchestration/references/anti-patterns.md
+11 -46
View File
@@ -1,48 +1,13 @@
# Anti-Patterns
Lessons learned from real multi-agent projects. Each anti-pattern was encountered at least once and caused real problems.
## Git & Branching
| Don't | Do Instead | Why |
|-------|------------|-----|
| Rebase feature branches | Regular merge | Rebase rewrites history and loses commits. When multiple chats contribute to a branch, rebase causes cascading regressions. |
| Squash merge PRs | Regular merge | Squash hides individual commits, making it impossible to revert a single fix. |
| Use worktrees on shared branches | Separate clones | Worktrees share the git index. Parallel teams stepping on each other's staging area causes confusion. |
| Push directly to main | Feature branch → PR → merge | Direct pushes bypass review and can't be reverted cleanly. |
| Force push (`--force`) | Fix forward or revert | Force push destroys remote history that other teams may have pulled. |
## Team Roles
| Don't | Do Instead | Why |
|-------|------------|-----|
| Producer writes code | Producer only plans, merges, files issues | When the coordinator starts coding, they lose track of the big picture. Fixes in the producer chat often conflict with dev team work. |
| One agent does everything | Separate agents for dev, QA, coordination | Context isolation prevents cross-contamination. QA shouldn't have edit tools. |
| Skip the brainstorm | Run brainstorm → plan → execute | Jumping straight to code produces generic results. Brainstorms surface edge cases early. |
| Vague brainstorm prompts ("you are the team") | Name each agent with distinct perspective | Named agents with defined tendencies produce real debate. Generic prompts produce bland consensus. |
## Sprint Management
| Don't | Do Instead | Why |
|-------|------------|-----|
| Batch "fix everything" commits | One commit per fix with issue reference | Batch commits make it impossible to track what was fixed. If one fix causes a regression, you can't revert just that fix. |
| Keep bugs only in chat | File GitHub Issues | Chat context dies when the conversation ends. Issues persist across all chats and teams. |
| Skip handoff docs (done.md) | Mandatory done.md + PROJECT_BRIEF update | Without handoff docs, the next chat starts blind. It may overwrite work or duplicate effort. |
| Skip progress tracker | Update progress.md after each phase | Without a progress tracker, context overflow recovery is impossible. The new chat doesn't know where the old one left off. |
| Rush the AI with time pressure | "Take your time, do it right" | Time pressure makes the LLM skip edge cases, write less tests, and produce lower quality code. "No rush" produces better results. |
## Testing & QA
| Don't | Do Instead | Why |
|-------|------------|-----|
| Merge before testing | Playtest → file issues → fix → merge | Merging untested code creates a broken main branch. QA can't test against a moving target. |
| QA modifies source code | QA only files issues, dev team fixes | QA fixes often miss context and introduce new bugs. Separation of concerns. |
| Close issues without verification | Dev fixes → QA verifies → close | Self-closing issues skips verification. The fix might not actually work. |
## Context & Communication
| Don't | Do Instead | Why |
|-------|------------|-----|
| Assume chats share memory | Files are the shared memory | Each chat is a fresh context. PROJECT_BRIEF.md and progress.md are the only things that survive. |
| Keep decisions in conversation | Write decisions to files | Decisions made in chat are lost when the chat closes. Write to docs/ or GitHub Issues. |
| Relay raw error logs between teams | Summarize and file as GitHub Issue | Raw logs waste context tokens. Summarize: component, steps, expected, actual. |
| Avoid | Prefer | Why |
|---|---|---|
| One agent owns planning, implementation, testing, and approval | Keep Producer, Dev, and optional QA responsibilities distinct | Independent perspectives reduce blind spots without requiring ceremony for every change. |
| Hardcoded tool or model allowlists | Inherit the developer's enabled tools and selected model | Extensions and MCP tools remain available without plugin updates. |
| A mandatory process for every change | Scale planning, review, and QA to risk | Small changes stay fast; high-impact changes receive more scrutiny. |
| Universal Git command recipes | Follow repository contribution and branch policy | Projects use different remotes, protections, and merge strategies. |
| Rewriting shared history or discarding unknown work | Preserve work and coordinate destructive actions | Parallel sessions and contributors may depend on existing state. |
| Large plans that duplicate project documentation | Record only outcomes, constraints, decisions, and next actions | Concise context is easier to maintain and recover. |
| Bugs and decisions kept only in chat | Use the repository's issue tracker and durable context | Future sessions can discover them. |
| QA fixes application source | QA reports behavior; Dev implements fixes | Separation preserves independent verification. |
| Treating every automated suggestion as a requirement | Assess relevance, confidence, scope, and practical risk | Review should improve the product, not expand scope without limit. |
skills/ai-team-orchestration/references/brainstorm-format.md
+10 -15
View File
@@ -14,16 +14,16 @@ This is a creative session — no idea is too wild in Phase 1.
- Thinks about: user delight, accessibility, "would this be fun?"
- Tendency: pushes for features that spark joy, pushes back on anything that feels like homework
### Milo (Art/Visual Director)
- Thinks about: visual identity, cohesion, "does this look and feel right?"
- Tendency: wants everything beautiful, sometimes at odds with engineering feasibility
### Milo (Experience/Design Perspective)
- Thinks about: accessibility, presentation, content, cohesion, "does this feel right?"
- Tendency: advocates for user experience, sometimes at odds with engineering feasibility
### Nova (Frontend Engineer)
- Thinks about: component architecture, state management, "can we actually build this?"
### Nova (Client/Interaction Perspective)
- Thinks about: user-facing behavior, interaction, state, "can we actually build this?"
- Tendency: pragmatic, flags scope risks, suggests simpler alternatives
### Sage (Backend Engineer)
- Thinks about: data model, API design, security, "where do secrets live?"
### Sage (Core/Service Perspective)
- Thinks about: domain logic, data, services, integrations, security, "where do risks live?"
- Tendency: security-first, sometimes over-engineers, good at spotting edge cases
### Remy (Producer)
@@ -49,12 +49,7 @@ Phase 3 — Final Pitches:
Each concept includes: name, description, pros, cons, estimated effort.
Team vote with brief justification from each voter.
Output all phases as separate files:
- docs/brainstorm/01-free-ideation.md
- docs/brainstorm/02-discussion.md
- docs/brainstorm/03-concept-[A/B/C...].md (one per concept)
- docs/brainstorm/04-team-vote.md
- docs/brainstorm/05-summary.md
Write the result to one concise design note unless the project needs separate artifacts.
```
## Tips
@@ -62,12 +57,12 @@ Output all phases as separate files:
- **Name each agent** — "you are the full team" produces bland consensus
- **Define tendencies** — gives the LLM permission to disagree
- **Require disagreements** — "at least 2 genuine disagreements" prevents groupthink
- **Separate files** — forces structured output, makes it reviewable
- **Keep the output proportional** — one note is usually enough
- **Customize personas** — adjust for your domain (e.g., replace Kira with a Data Scientist for ML projects)
## Mini-Brainstorm (Quick Version)
For smaller decisions:
For smaller decisions (e.g., "how should we implement the scoreboard?"):
```
Run a team brainstorm about [TOPIC].
skills/ai-team-orchestration/references/project-brief-template.md
+56 -133
View File
@@ -1,147 +1,70 @@
# PROJECT_BRIEF.md Template
Copy this template to your project root and fill in every section. **Do not abbreviate sections 12-14** — they are critical for cross-chat context survival.
---
Use this only when the project benefits from durable context across sessions. Keep it concise and omit irrelevant sections.
```markdown
# PROJECT_BRIEF.md — [Project Name]
# PROJECT_BRIEF.md - [Project Name]
> Last updated: [date] | Sprint [N] | Status: [In Progress / Complete]
> Last updated: [date]
## 1. Project Overview
## 1. Goal and Users
[3-4 sentences describing what the project is, who it's for, and the core goal.]
[What the project is, who it serves, and the outcome it should create.]
## 2. Concept / Product Description
## 2. Current Scope
[Detailed description of the product — user flows, key features, narrative if applicable.]
**In scope**
- [outcome]
## 3. Tech Stack
**Out of scope**
- [explicit exclusion]
- **Frontend:** [framework, language, key libraries]
- **Backend:** [runtime, framework, database]
- **Hosting:** [platform, CDN, storage]
- **Testing:** [test framework, E2E tool]
- **CI/CD:** [pipeline tool]
## 3. Stack and Architecture
## 4. Architecture
- Runtime/language: [value]
- Frameworks/libraries: [value]
- Data/services: [value]
- Deployment: [value or not applicable]
- Tests/checks: [verified commands]
```
┌─────────────────────────────────────────┐
│ Frontend │
│ [Main Component] → [Sub Components] │
└──────────────┬──────────────────────────┘
│ HTTPS
┌──────────────▼──────────────────────────┐
│ Backend API │
│ [Endpoints and their purpose] │
└──────────────┬──────────────────────────┘
│
┌──────────────▼──────────────────────────┐
│ Storage / Database │
│ [Tables, collections, env vars] │
└─────────────────────────────────────────┘
```
## 5. Key Files Map
| Area | Path | Contents |
|------|------|----------|
| Entry point | `src/main.tsx` | App bootstrap |
| API | `api/src/` | Server-side logic |
| Config | `api/src/config/` | Server-only configuration |
| Tests | `tests/` | E2E and API tests |
| Sprint docs | `docs/sprint-N/` | Plans, progress, done |
## 6. Team Roles
| Agent | Name | Role |
|-------|------|------|
| Producer | Remy | Sprint plans, coordination, merging |
| Frontend | Nova | UI components, state, client logic |
| Backend | Sage | API, auth, database, security |
| Art/CSS | Milo | Visual design, animations, polish |
| QA | Ivy | Testing, bug filing, sign-off |
| Product | Kira | UX design, mechanics, feature specs |
| DevOps | Dash | CI/CD, deployment, infrastructure |
## 7. Sprint Status
| Sprint | Name | Status | Scope |
|--------|------|--------|-------|
| 0 | Architecture | ✅ Done | Tech stack, project structure, design guide |
| 1 | Core Features | 🔨 In Progress | [scope description] |
## 8. Current State (rewrite every sprint)
**What works:**
- [List of working features]
**What doesn't work yet:**
- [Known issues]
**What's next:**
- [Next sprint goals]
## 9. Security Rules
1. Secrets live in environment variables only — never in code or git.
2. [Auth approach]
3. [Additional security rules]
## 10. How to Run Locally
```bash
npm install
cd api && npm install
cp api/local.settings.json.example api/local.settings.json
npm run dev:all
```
## 11. How to Deploy
[Pipeline description, env var locations, deployment steps]
## 12. Cross-Chat Handoff Protocol
Every sprint chat must do these before finishing:
1. Write `docs/sprint-N/done.md` — what was built, what's not done, what needs manual setup, files changed/created
2. Update PROJECT_BRIEF.md: Section 7 (mark sprint done) + Section 8 (rewrite current state)
3. Commit all changes with descriptive message: `sprint-N: <summary>`
This is how context survives across chats. If skipped, the next chat starts blind and may overwrite or duplicate work. The repo is the shared memory — keep it accurate.
## 13. Bug & Fix Tracking
Bugs are tracked as GitHub Issues on the repo. Single source of truth for all teams.
**For QA:** File bugs as GitHub Issues with labels (`bug`, `severity:blocker/major/minor`). Include: component, steps to reproduce, expected vs actual. When no blockers found: write `docs/qa/sprint-N-signoff.md` with test count, pass rate, explicit "no blockers" statement.
**For Dev Team:** Check GitHub Issues before starting work. Fix blockers and majors before polish. Use GitHub closing keywords in commits: `fix: description (Fixes #42)`. For reference-only, use `Refs #42`.
**For DevOps:** File infrastructure issues with label `infra`.
**For feature ideas:** add to `docs/ideas-backlog.md`.
## 14. Multi-Repo Setup
Each team works in their own separate clone of the repo. No worktrees. Everyone works on their own branch, pushes to origin, creates PRs.
**Teams:**
- Producer on `main` (coordination hub)
- Dev Team on `feature/sprint-N`
- QA on `feature/qa-N`
- DevOps on `feature/devops-N` (only when needed)
**Setup:**
```bash
git clone <repo> <folder-name>
cd <folder-name>
git checkout -b <branch-name>
npm install
```
**Branch strategy:** Feature branches → PR → regular merge to main. Never push directly to main. Never squash. Never rebase feature branches (causes commit loss).
[Short architecture description or diagram when useful.]
## 4. Key Files
| Area | Path | Purpose |
|---|---|---|
| [area] | `[path]` | [purpose] |
## 5. How to Work
- Setup: [verified command or link]
- Run: [verified command or link]
- Test: [verified commands]
- Deploy: [verified process or not applicable]
- Repository rules: [links to contribution/security instructions]
## 6. Safety and Constraints
- [secrets/privacy/data rules]
- [compatibility or reliability invariant]
- [operational constraint]
## 7. Current State
**Working**
- [item]
**Known issues**
- [issue/link]
**Next**
- [next outcome]
## 8. Team and Handoff
- Producer: scope, coordination, and merge
- Dev: implementation and verification
- QA: optional independent behavioral verification
Record material decisions, blockers, and the next action here or in the active plan. Use GitHub Issues or the repository's tracker for bugs and follow-up work.
```
skills/ai-team-orchestration/references/sprint-plan-template.md
+49 -114
View File
@@ -1,140 +1,75 @@
# Sprint Plan Template
# Work Plan Template
## Plan File
Save as `docs/sprint-N/plan.md`:
Use this for substantial work. Small, clear changes can proceed directly from the issue or request.
```markdown
# Sprint N — [Name]
# [Work Item] - Plan
> Sprint Goal: [one sentence describing the deliverable]
> Branch: feature/sprint-N
> Estimated effort: [time estimate]
## Goal
## Prioritized Task List
[One observable outcome.]
| # | Task | Owner | Est | Description |
|---|------|-------|-----|-------------|
| 1 | [task] | Nova | 1h | [what to build] |
| 2 | [task] | Sage | 2h | [what to build] |
| 3 | [task] | Milo | 1h | [what to style] |
## Context
## Work Schedule
- Relevant issue/request: [link or summary]
- Repository instructions: [links]
- Important constraints: [list]
### Phase 1: [Name] (tasks 1-3)
- Build [component]
- Checkpoint commit after phase
## In Scope
### Phase 2: [Name] (tasks 4-6)
- Build [component]
- Checkpoint commit after phase
- [deliverable]
### Phase 3: Polish & Integration
- Integration testing
- Bug fixes
- Final commit
## Out of Scope
## Success Criteria
- [explicit exclusion]
- [ ] [Testable criterion 1]
- [ ] [Testable criterion 2]
- [ ] [Testable criterion 3]
- [ ] All tests pass
- [ ] No console errors
## Tasks
## What's NOT in This Sprint
1. [task]
2. [task]
3. [task]
| Feature | Reason |
|---------|--------|
| [cut feature] | [why — scope, complexity, not needed yet] |
## Acceptance Criteria
## Agent Prompt
- [ ] [observable behavior]
- [ ] Relevant repository checks pass
- [ ] Documentation/context is updated when behavior or operation changed
> Read PROJECT_BRIEF.md, then read docs/sprint-N/plan.md. Execute Sprint N.
>
> First: git pull origin main && git checkout -b feature/sprint-N
>
> Close GitHub Issues in commits: "fix: description (Fixes #NN)"
> Update docs/sprint-N/progress.md after each phase.
> When done, push and create PR: git push origin feature/sprint-N
> Follow Sections 12-14 of PROJECT_BRIEF.md.
## Verification
- Automated: [commands or checks]
- Manual: [focused scenarios, if useful]
- Independent review: required / optional / not needed - [reason]
- QA: required / optional / not needed - [reason]
## Risks and Decisions
- [risk or material decision]
## Next Action
[owner and immediate next step]
```
## Progress Tracker
## Progress Note
Create `docs/sprint-N/progress.md` at sprint start:
For long-running work, keep a short progress note:
```markdown
# Sprint N — Progress Tracker
# [Work Item] - Progress
> If context overflows, start a new chat:
> "Read PROJECT_BRIEF.md and docs/sprint-N/progress.md.
> Continue from where it left off."
## Task Status
| # | Task | Status | Notes |
|---|------|--------|-------|
| 1 | [task] | ⬜ Not started | |
| 2 | [task] | 🔨 In progress | |
| 3 | [task] | ✅ Done | |
| 4 | [task] | ❌ Blocked | [reason] |
## Bugs Found
| # | Description | Severity | Status | Fix |
|---|-------------|----------|--------|-----|
| 1 | [bug] | blocker/major/minor | open/fixed | [commit or PR] |
## Notes
[Free-form notes about decisions, issues, or context for recovery]
- Completed: [items]
- In progress: [item]
- Blocked: [issue or none]
- Decisions: [material decisions]
- Verification so far: [results]
- Next action: [specific action]
```
## Done File
## Dev Handoff
Write `docs/sprint-N/done.md` at sprint end:
```markdown
# Sprint N — Done
## What Was Built
- [Feature 1]
- [Feature 2]
## What's NOT Done
- [Deferred item — why]
## Files Changed/Created
- `src/components/NewComponent.tsx` — [purpose]
- `api/src/functions/newEndpoint.ts` — [purpose]
## Manual Setup Required
- [Any env vars, config, or manual steps needed]
## Known Issues
- [Issue — tracked as GitHub Issue #NN]
```
## QA Sign-off Template
```markdown
# QA Sprint N Sign-Off
Date: [date]
Tester: Ivy (QA)
## Test Results
- Tests run: X
- Tests passed: X
- Tests failed: 0
## Blockers
NONE
## Issues Filed
- #NN — [description] (severity: minor)
## Result
✅ PASS — No blockers. Sprint N is ready to merge.
```text
Read the repository instructions, PROJECT_BRIEF.md when present, and this plan.
Implement the in-scope work, run the listed verification, update durable context
when needed, and prepare a pull request. Do not merge.
```