Awesome/awesome-copilot
1
0
Fork 0
mirror of https://github.com/github/awesome-copilot.git synced 2026-08-18 07:06:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore: publish from main

Browse Source
This commit is contained in:
github-actions[bot]
2026-07-30 01:50:17 +00:00
parent ceaedd75c2
commit cf360fd227
22 changed files with 538 additions and 1178 deletions
Download Patch File Download Diff File Expand all files Collapse all files
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.
```