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

Merge upstream/main into add-daily-focus-board-skill

Browse Source 
Resolve the .codespellrc conflict by retaining both the daily-focus-board checkin key and upstream ACI term.

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

Copilot-Session: fd1eae93-cc9f-4777-812c-a2a9872e1c2b
This commit is contained in:
Jenny Ferries
2026-07-29 21:22:17 -07:00
parent 0612442158 c46b4a919a
commit 96ca38efa1
118 changed files with 22682 additions and 620 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.
```
skills/azure-container-registry-cli/SKILL.md
+90
View File
@@ -0,0 +1,90 @@
---
name: azure-container-registry-cli
description: 'Manage Azure Container Registry via the az acr CLI including registries, images, cloud builds, ACR Tasks, authentication, tokens, geo-replication, and networking. Use when working with ACR, az acr commands, pushing/importing/purging container images in Azure, or when the user mentions Azure Container Registry.'
---
# Azure Container Registry CLI
Manage Azure Container Registry (ACR) resources using the `az acr` command group of the Azure CLI.
**CLI:** `az acr` ships with core Azure CLI — no extension required (the `acrtransfer` extension is only needed for export/import pipelines).
## Prerequisites
```bash
# Install Azure CLI
brew install azure-cli # macOS
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash # Linux
winget install Microsoft.AzureCLI # Windows
# Sign in and select subscription
az login
az account set --subscription {subscription-id}
```
## Quick Start
```bash
# Create a registry (SKU: Basic | Standard | Premium)
az acr create --resource-group {rg} --name {registry} --sku Standard
# Authenticate Docker/Podman against the registry
az acr login --name {registry}
# Build and push in the cloud — no local Docker needed
az acr build --registry {registry} --image app:v1 .
# Copy an image from another registry without pull/push
az acr import --name {registry} --source mcr.microsoft.com/hello-world:latest
# List repositories and tags
az acr repository list --name {registry} --output table
az acr repository show-tags --name {registry} --repository app --orderby time_desc
# Diagnose registry connectivity and configuration
az acr check-health --name {registry} --yes
```
## Key Principles
- **Prefer `az acr build` / ACR Tasks** over local `docker build` + `docker push`: builds run in Azure, work without a local daemon, and integrate with triggers.
- **Prefer `az acr import`** to move images between registries: it is server-side, faster, and requires no local storage.
- **Never enable the admin user for production** — use Microsoft Entra identities (RBAC roles `AcrPull`/`AcrPush`, or `Container Registry Repository Reader`/`Writer` on ABAC-enabled registries), repository-scoped tokens, or managed identities.
- **Premium-only features**: geo-replication, private endpoints, retention policies, connected registries, agent pools. (Repository-scoped tokens work in all tiers; zone redundancy is automatic in all tiers in supported regions.)
## CLI Structure
```
az acr
├── create / delete / list / show / update # Registry lifecycle
├── login # Docker credential helper (or --expose-token)
├── check-health / check-name / show-usage # Diagnostics & quota
├── build # Cloud image build (quick task)
├── run # Run a command / multi-step task once
├── task # ACR Tasks (triggers, timers, logs, runs)
├── agentpool # Dedicated task agent pools (Premium)
├── import # Server-side image copy into the registry
├── repository # List/show/delete/untag repos & tags, lock images
├── manifest # Manifest metadata, delete, OCI referrers
├── credential # Admin user credentials (avoid in production)
├── token / scope-map # Repository-scoped tokens (Premium)
├── replication # Geo-replication (Premium)
├── network-rule # IP network rules
├── private-endpoint-connection # Private Link approvals
├── config # content-trust, retention, soft-delete, ...
├── cache / credential-set # Artifact cache (pull-through cache) rules
├── webhook # Push/delete event webhooks
├── connected-registry # On-premises / IoT connected registries
└── export-pipeline / import-pipeline / pipeline-run # acrtransfer extension
```
## Reference Files
Read the relevant reference file based on the user's task. Each file contains complete command syntax and examples for its domain.
| File | When to read | Covers |
|---|---|---|
| `references/auth-and-security.md` | Login failures, permissions, CI/CD or AKS pull access | `az acr login` (incl. `--expose-token`), Entra RBAC roles, service principals, managed identities, `--attach-acr` for AKS, repository-scoped tokens & scope maps, admin user, content trust |
| `references/build-and-tasks.md` | Building images in Azure, automation, CI triggers | `az acr build`, `az acr run`, multi-step task YAML, `az acr task` (git/base-image/timer triggers, logs, runs), agent pools |
| `references/images-and-artifacts.md` | Managing repos, tags, cleanup, storage costs | `az acr import`, repository & manifest commands, untag vs delete, purge (`acr purge`), image locking, retention policy, soft delete, artifact cache, `show-usage` |
| `references/networking-and-geo.md` | Multi-region, private access, edge scenarios | Geo-replication, zone redundancy, private endpoints, network rules, dedicated data endpoints, connected registries, registry transfer pipelines |
skills/azure-container-registry-cli/references/auth-and-security.md
+174
View File
@@ -0,0 +1,174 @@
# Authentication & Security
## Table of Contents
- [Individual Login](#individual-login)
- [Microsoft Entra RBAC Roles](#microsoft-entra-rbac-roles)
- [Service Principals](#service-principals)
- [Managed Identities](#managed-identities)
- [AKS Integration](#aks-integration)
- [Repository-Scoped Tokens](#repository-scoped-tokens)
- [Admin User](#admin-user)
- [Content Trust](#content-trust)
---
## Individual Login
```bash
# Standard login — wires Docker/Podman credentials via your az login identity
az acr login --name {registry}
# Without a Docker daemon: get an Entra access token and pipe it to docker login
LOGIN_SERVER=$(az acr show --name {registry} --query loginServer --output tsv)
az acr login --name {registry} --expose-token --query accessToken --output tsv | \
docker login $LOGIN_SERVER --username 00000000-0000-0000-0000-000000000000 --password-stdin
```
Notes:
- `az acr login` tokens are valid for 3 hours; re-run on expiry.
- Resolve the login server with `az acr show --name {registry} --query loginServer --output tsv` rather than hardcoding it: it is usually `{registry}.azurecr.io`, but sovereign clouds use other suffixes and registries with a domain name label scope get a hash suffix.
## Microsoft Entra RBAC Roles
The applicable data-plane roles depend on the registry's **role assignment permissions mode** — check it first:
```bash
az acr show --name {registry} --query roleAssignmentMode --output tsv
# LegacyRegistryPermissions -> use AcrPull/AcrPush/AcrDelete
# AbacRepositoryPermissions -> use Container Registry Repository Reader/Writer/Contributor
```
**Legacy mode (RBAC Registry Permissions):**
| Role | Permissions |
|---|---|
| `AcrPull` | Pull images |
| `AcrPush` | Pull + push images |
| `AcrDelete` | Delete images |
| `AcrImageSigner` | Sign images (content trust) |
| `Contributor`/`Owner` | Full control-plane management + push/pull |
**ABAC-enabled mode (RBAC Registry + ABAC Repository Permissions):** `AcrPull`/`AcrPush`/`AcrDelete` are **not honored**, and `Owner`/`Contributor`/`Reader` grant control-plane only. Use instead:
| Role | Permissions |
|---|---|
| `Container Registry Repository Reader` | Read images, tags, metadata (add ABAC conditions to scope to repositories) |
| `Container Registry Repository Writer` | Read + write/update |
| `Container Registry Repository Contributor` | Read + write + delete |
| `Container Registry Repository Catalog Lister` | List repositories — assign only when the identity must enumerate the catalog (e.g., `az acr repository list`); not needed for pull/push of known repositories |
```bash
# Get the registry resource ID
ACR_ID=$(az acr show --name {registry} --query id --output tsv)
# Grant pull access to a user, group, service principal, or managed identity
az role assignment create --assignee {principal-id} --scope $ACR_ID --role AcrPull
# List who has access
az role assignment list --scope $ACR_ID --output table
```
## Service Principals
For CI/CD systems that cannot use OIDC/managed identity:
```bash
# Create an SP scoped to pull only
ACR_ID=$(az acr show --name {registry} --query id --output tsv)
az ad sp create-for-rbac --name {sp-name} --scopes $ACR_ID --role AcrPull
# Docker login with the SP — pipe the secret via stdin, never pass it as an argument
# (printf with a quoted variable preserves whitespace/glob characters exactly)
printf '%s' "$SP_PASSWORD" | docker login $LOGIN_SERVER --username {appId} --password-stdin
```
Prefer federated credentials (OIDC) over SP passwords in GitHub Actions / Azure DevOps when possible.
## Managed Identities
For Azure compute (VM, App Service, Container Apps, Functions):
```bash
# Assign a system-assigned identity and grant it pull
az vm identity assign --name {vm} --resource-group {rg}
PRINCIPAL_ID=$(az vm show --name {vm} --resource-group {rg} --query identity.principalId --output tsv)
az role assignment create --assignee $PRINCIPAL_ID --scope $ACR_ID --role AcrPull
```
App Service / Container Apps then pull with `--assign-identity` + `--acr-identity` style flags of their own CLIs — no registry password needed.
## AKS Integration
```bash
# Attach at cluster creation
az aks create --name {cluster} --resource-group {rg} --attach-acr {registry}
# Attach/detach an existing cluster (grants AcrPull to the kubelet identity)
az aks update --name {cluster} --resource-group {rg} --attach-acr {registry}
az aks update --name {cluster} --resource-group {rg} --detach-acr {registry}
# Validate the cluster can reach the registry
az aks check-acr --name {cluster} --resource-group {rg} --acr {registry}.azurecr.io
```
`--attach-acr` requires Owner or User Access Administrator on the registry. Cross-subscription attach works by passing the full ACR resource ID.
⚠️ `--attach-acr` assigns `AcrPull`, which is **not honored on ABAC-enabled registries** (`roleAssignmentMode` = `AbacRepositoryPermissions`). For those, assign the ABAC roles to the kubelet identity manually:
```bash
ACR_ID=$(az acr show --name {registry} --query id --output tsv)
KUBELET_ID=$(az aks show --name {cluster} --resource-group {rg} \
--query identityProfile.kubeletidentity.objectId --output tsv)
az role assignment create --assignee $KUBELET_ID --scope $ACR_ID \
--role "Container Registry Repository Reader"
# "Container Registry Repository Catalog Lister" is NOT needed for pulls —
# only add it if the identity must list repositories
```
## Repository-Scoped Tokens
Available in all service tiers. Fine-grained, non-Entra credentials (e.g., external partners, IoT devices):
```bash
# 1. Create a scope map (actions: content/read, content/write, content/delete, metadata/read, metadata/write)
az acr scope-map create --name {scope-map} --registry {registry} \
--repository app content/read metadata/read \
--description "Pull-only access to app"
# 2. Create a token bound to the scope map
az acr token create --name {token} --registry {registry} --scope-map {scope-map}
# 3. Generate/rotate passwords (up to 2, optional expiry)
az acr token credential generate --name {token} --registry {registry} --password1 --expiration-in-days 30
# Login with the token — pipe the password via stdin, never pass it as an argument
printf '%s' "$TOKEN_PWD" | docker login $LOGIN_SERVER --username {token} --password-stdin
# Disable or delete
az acr token update --name {token} --registry {registry} --status disabled
az acr token delete --name {token} --registry {registry} --yes
```
## Admin User
Single account, full push/pull on the whole registry, not auditable per user — **keep disabled in production**:
```bash
az acr update --name {registry} --admin-enabled false # recommended
az acr credential show --name {registry} # view username/passwords (if enabled)
az acr credential renew --name {registry} --password-name password2 # rotate
```
Legitimate uses: quick local tests, services that only accept username/password and cannot use tokens.
## Content Trust (deprecated)
Docker Content Trust (DCT) is being retired: **since May 31, 2026 it cannot be enabled on new registries** (or on registries that never enabled it), and it will be removed entirely on March 31, 2028. Do not set up DCT — sign images with **Notation (Notary Project)** and store signatures as OCI artifacts instead; see "Transition from Docker Content Trust to Notary Project" in the ACR docs.
```bash
# Registries with legacy DCT only — inspect or disable the existing configuration
az acr config content-trust show --registry {registry}
az acr config content-trust update --registry {registry} --status disabled
```
Legacy DCT signers needed `AcrImageSigner` in addition to `AcrPush`.
skills/azure-container-registry-cli/references/build-and-tasks.md
+147
View File
@@ -0,0 +1,147 @@
# Builds & ACR Tasks
## Table of Contents
- [Quick Build (az acr build)](#quick-build-az-acr-build)
- [Run a Command or Multi-Step Task Once (az acr run)](#run-a-command-or-multi-step-task-once-az-acr-run)
- [ACR Tasks (az acr task)](#acr-tasks-az-acr-task)
- [Triggers](#triggers)
- [Multi-Step Task YAML](#multi-step-task-yaml)
- [Agent Pools](#agent-pools)
---
## Quick Build (az acr build)
Builds in Azure and pushes to the registry — no local Docker daemon required:
```bash
# Build from the current directory and push
az acr build --registry {registry} --image app:v1 .
# Custom Dockerfile, build args, target platform
az acr build --registry {registry} --image app:v1 \
--file docker/Dockerfile.prod \
--build-arg VERSION=1.2.3 \
--platform linux/amd64 .
# Cross-platform: each build produces ONE single-architecture image for the target platform
az acr build --registry {registry} --image app:v1-arm64 --platform linux/arm64 .
# For a true multi-arch image, build once per platform under arch-specific tags, then
# assemble and push a manifest list (docker manifest create/push, or docker buildx locally)
# Build directly from a Git repo (no local clone)
az acr build --registry {registry} --image app:v1 https://github.com/{org}/{repo}.git#{branch}:{folder}
# Build without pushing (validation only)
az acr build --registry {registry} --image app:test --no-push .
```
Notes:
- The build context is uploaded; use a `.dockerignore` to keep it small.
- Tag with a unique value per build (git SHA, run ID) — avoid relying on `latest`.
## Run a Command or Multi-Step Task Once (az acr run)
```bash
# Run a container command in the registry's task runner (context /dev/null = no upload)
az acr run --registry {registry} --cmd '{registry}.azurecr.io/app:v1' /dev/null
# Execute a multi-step task file against the current directory
az acr run --registry {registry} --file acb.yaml .
```
## ACR Tasks (az acr task)
Persistent, triggerable build definitions:
```bash
# Create a task that builds on every commit to main
az acr task create --registry {registry} --name build-app \
--image "app:{{.Run.ID}}" \
--context https://github.com/{org}/{repo}.git#main \
--file Dockerfile \
--git-access-token {pat} \
--commit-trigger-enabled true \
--base-image-trigger-enabled true
# Manually trigger, list, inspect
az acr task run --registry {registry} --name build-app
az acr task list --registry {registry} --output table
az acr task list-runs --registry {registry} --name build-app --output table
az acr task logs --registry {registry} --name build-app # latest run
az acr task logs --registry {registry} --run-id {run-id}
# Update / disable / delete
az acr task update --registry {registry} --name build-app --image "app:{{.Run.ID}}"
az acr task update --registry {registry} --name build-app --status Disabled
az acr task delete --registry {registry} --name build-app --yes
```
Useful run variables for `--image`: `{{.Run.ID}}`, `{{.Run.Commit}}`, `{{.Run.Branch}}`, `{{.Run.Date}}`.
⚠️ On **ABAC-enabled registries** (`roleAssignmentMode` = `AbacRepositoryPermissions`), tasks and quick builds/runs have no default access to the source registry. Pass `--source-acr-auth-id [caller]` to `az acr build`/`az acr run`, and `--source-acr-auth-id [system]` (or a user-assigned identity resource ID) to `az acr task create`/`update`, then grant that identity the `Container Registry Repository ...` roles. Ensure the task actually has that identity — add `--assign-identity [system]` at creation, or run `az acr task identity assign` on an existing task, before referencing it.
## Triggers
```bash
# Timer trigger (cron in UTC) — e.g., nightly rebuild
az acr task timer add --registry {registry} --name build-app \
--timer-name nightly --schedule "0 2 * * *"
az acr task timer list --registry {registry} --name build-app
az acr task timer remove --registry {registry} --name build-app --timer-name nightly
```
- **Commit trigger**: rebuild on push to the tracked branch (`--commit-trigger-enabled`).
- **Base image trigger**: rebuild automatically when the base image (e.g., a patched `mcr.microsoft.com` image) is updated (`--base-image-trigger-enabled`) — key for OS/framework patching.
- **Timer trigger**: cron schedules; also the standard way to schedule `acr purge` cleanup (see `images-and-artifacts.md`).
Tasks that access other registries or Azure resources can use an identity:
```bash
az acr task identity assign --registry {registry} --name build-app # system-assigned
az acr task credential add --registry {registry} --name build-app \
--login-server {other-registry}.azurecr.io --use-identity [system]
```
## Multi-Step Task YAML
`acb.yaml` — build, test, then push only on success:
```yaml
version: v1.1.0
steps:
- build: -t $Registry/app:{{.Run.ID}} -f Dockerfile .
- cmd: $Registry/app:{{.Run.ID}} run-tests
- push:
- $Registry/app:{{.Run.ID}}
```
```bash
# Run once
az acr run --registry {registry} --file acb.yaml .
# Or create a triggered task from the YAML
az acr task create --registry {registry} --name build-test-push \
--file acb.yaml \
--context https://github.com/{org}/{repo}.git#main \
--git-access-token {pat}
```
## Agent Pools
Premium SKU. Dedicated task compute — for more CPU, or one of the two supported ways to run tasks against a network-restricted registry (the other being trusted services + the task network bypass policy, see `networking-and-geo.md`):
```bash
az acr agentpool create --registry {registry} --name pool1 --tier S2 # S1/S2/S3/I6
# For the firewall/VNet scenario, the pool MUST be attached to a subnet that can
# reach the registry's private endpoint — without --subnet-id it runs outside the VNet
az acr agentpool create --registry {registry} --name pool1 --tier S2 \
--subnet-id /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Network/virtualNetworks/{vnet}/subnets/{subnet}
az acr agentpool list --registry {registry} --output table
# Target the pool
az acr build --registry {registry} --agent-pool pool1 --image app:v1 .
az acr task create --registry {registry} --name build-app --agent-pool pool1 ...
```
skills/azure-container-registry-cli/references/images-and-artifacts.md
+170
View File
@@ -0,0 +1,170 @@
# Images & Artifacts
## Table of Contents
- [Import Images (Server-Side Copy)](#import-images-server-side-copy)
- [Repositories & Tags](#repositories--tags)
- [Manifests](#manifests)
- [Untag vs Delete](#untag-vs-delete)
- [Purge Old Images (acr purge)](#purge-old-images-acr-purge)
- [Lock Images](#lock-images)
- [Retention Policy & Soft Delete](#retention-policy--soft-delete)
- [Artifact Cache (Pull-Through Cache)](#artifact-cache-pull-through-cache)
- [Storage Usage](#storage-usage)
---
## Import Images (Server-Side Copy)
Preferred over `docker pull` + `docker push` — no local storage, keeps multi-arch manifests intact:
```bash
# From a public registry
az acr import --name {registry} --source mcr.microsoft.com/hello-world:latest
az acr import --name {registry} --source docker.io/library/nginx:1.27 --image nginx:1.27
# From another ACR in the same tenant (by resource ID, no credentials needed)
az acr import --name {registry} \
--source app:v1 \
--registry /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.ContainerRegistry/registries/{src-registry}
# From a private registry with credentials
az acr import --name {registry} --source private.example.com/app:v1 \
--username {user} --password {password}
# Overwrite an existing tag
az acr import --name {registry} --source docker.io/library/nginx:1.27 --image nginx:1.27 --force
```
## Repositories & Tags
```bash
az acr repository list --name {registry} --output table
# Tags, newest first, with digest and timestamps
az acr repository show-tags --name {registry} --repository app \
--orderby time_desc --detail --output table
az acr repository show --name {registry} --image app:v1 # tag attributes
az acr repository show --name {registry} --repository app # repo attributes
```
## Manifests
```bash
# Metadata for all manifests in a repo (digest, tags, size, timestamps)
az acr manifest list-metadata --registry {registry} --name app --output table
# One manifest's metadata / raw content
az acr manifest show-metadata --registry {registry} --name app:v1
az acr manifest show --registry {registry} --name app@sha256:{digest}
# Find untagged (orphaned) manifests
az acr manifest list-metadata --registry {registry} --name app \
--query "[?tags==null].digest" --output tsv
```
## Untag vs Delete
```bash
# Untag: removes only the tag; manifest + layers remain (still pullable by digest)
az acr repository untag --name {registry} --image app:v1
# Delete by tag: deletes the whole manifest and ALL other tags pointing to it
az acr repository delete --name {registry} --image app:v1 --yes
# Delete by digest (precise)
az acr repository delete --name {registry} --image app@sha256:{digest} --yes
# Delete an entire repository
az acr repository delete --name {registry} --repository app --yes
```
⚠️ Deleting by tag deletes the underlying manifest — other tags on the same image disappear too. Untag first if you only want to retire a tag name.
## Purge Old Images (acr purge)
`acr purge` runs as an ACR Task (container `mcr.microsoft.com/acr/acr-cli`):
```bash
# Dry run first — ALWAYS
az acr run --registry {registry} \
--cmd "acr purge --filter 'app:.*' --ago 30d --untagged --dry-run" /dev/null
# Delete tags older than 30 days matching the regex, plus untagged manifests
az acr run --registry {registry} \
--cmd "acr purge --filter 'app:.*' --ago 30d --untagged" /dev/null
# Keep the 5 most recent tags regardless of age
az acr run --registry {registry} \
--cmd "acr purge --filter 'app:.*' --ago 0d --keep 5 --untagged" /dev/null
# Schedule as a nightly task
az acr task create --registry {registry} --name purge-old-images \
--cmd "acr purge --filter 'app:.*' --ago 30d --untagged" \
--context /dev/null --schedule "0 3 * * *"
```
`--filter` takes `repository:tag-regex` and can be repeated for multiple repos.
⚠️ `--untagged` ignores `--ago`: it deletes **every** untagged manifest, including ones created moments ago (mid-push images, referrer artifacts). Omit `--untagged` if recent untagged manifests must survive — the age cutoff only applies to tagged images matched by `--filter`.
## Lock Images
Prevent overwrite or deletion of critical tags (e.g., released versions):
```bash
# Read-only: cannot be overwritten or deleted
az acr repository update --name {registry} --image app:v1 --write-enabled false
# Undeletable but still overwritable
az acr repository update --name {registry} --image app:v1 --delete-enabled false
# Unlock
az acr repository update --name {registry} --image app:v1 --write-enabled true --delete-enabled true
```
## Retention Policy & Soft Delete
Two distinct policies that **cannot be enabled at the same time**. Retention policy requires **Premium**; soft delete (preview) is available in **all tiers** but doesn't support geo-replicated or artifact-cache-enabled registries.
```bash
# Retention policy (Premium): auto-delete untagged manifests after N days (0 = immediately)
az acr config retention update --registry {registry} \
--status enabled --days 7 --type UntaggedManifests
az acr config retention show --registry {registry}
# Soft delete (preview, all tiers): recover deleted artifacts within 1-90 days
az acr config soft-delete update --registry {registry} --status enabled --days 7
az acr repository list-deleted --name {registry}
az acr manifest restore --registry {registry} --name app:v1
```
## Artifact Cache (Pull-Through Cache)
Cache upstream images (Docker Hub, MCR, GHCR, quay.io, ECR Public) in your registry — avoids rate limits and centralizes provenance:
```bash
# Optional: credentials for authenticated upstream (secrets live in Key Vault)
az acr credential-set create --registry {registry} --name dockerhub-creds \
--login-server docker.io \
--username-id https://{vault}.vault.azure.net/secrets/dh-user \
--password-id https://{vault}.vault.azure.net/secrets/dh-pass
# Cache rule: docker.io/library/* -> {registry}.azurecr.io/dockerhub/*
az acr cache create --registry {registry} --name dockerhub-cache \
--source-repo "docker.io/library/*" --target-repo "dockerhub/*" \
--cred-set dockerhub-creds
az acr cache list --registry {registry} --output table
```
Then `docker pull {registry}.azurecr.io/dockerhub/nginx:1.27` fetches through the cache.
## Storage Usage
```bash
# Consumed storage vs SKU quota (Basic 10 GB / Standard 100 GB / Premium 500 GB included)
az acr show-usage --name {registry} --output table
```
Layers are deduplicated and shared across repositories; `show-usage` reports actual billable storage.
skills/azure-container-registry-cli/references/networking-and-geo.md
+147
View File
@@ -0,0 +1,147 @@
# Networking & Geo-Replication
## Table of Contents
- [Geo-Replication](#geo-replication)
- [Zone Redundancy](#zone-redundancy)
- [Private Endpoints (Private Link)](#private-endpoints-private-link)
- [Public Network Rules](#public-network-rules)
- [Dedicated Data Endpoints](#dedicated-data-endpoints)
- [Connected Registry](#connected-registry)
- [Registry Transfer Pipelines](#registry-transfer-pipelines)
Geo-replication, private endpoints, public IP network rules, dedicated data endpoints, connected registries, and transfer pipelines require the **Premium** SKU. Zone redundancy is automatic in every tier.
---
## Geo-Replication
One registry, one login server, images served from the nearest region:
```bash
az acr replication create --registry {registry} --location westeurope
az acr replication list --registry {registry} --output table
az acr replication show --registry {registry} --name westeurope
az acr replication delete --registry {registry} --name westeurope
# Regional endpoint status (useful for webhook/replication debugging)
az acr replication update --registry {registry} --name westeurope --region-endpoint-enabled true
```
Pushes replicate automatically; clients keep pulling `{registry}.azurecr.io` and Traffic Manager routes to the closest replica.
## Zone Redundancy
Zone redundancy is **enabled automatically for all registries, in all tiers (Basic/Standard/Premium), in regions that support availability zones** — no flag, SKU, or action required, and it cannot be disabled. Geo-replicas in supported regions are also zone-redundant by default.
Do not rely on the `zoneRedundancy` property or the legacy `--zone-redundancy` flag: the property is a deprecated artifact that may display `Disabled` even though the registry is fully zone-redundant. Registries in regions without availability-zone support are the only exception — migrate them (via `az acr import` or a transfer pipeline) to a supported region.
## Private Endpoints (Private Link)
```bash
# 1. Disable network policies on the endpoint subnet if needed, then create the endpoint
az network private-endpoint create --resource-group {rg} --name {registry}-pe \
--vnet-name {vnet} --subnet {subnet} \
--private-connection-resource-id $(az acr show --name {registry} --query id --output tsv) \
--group-ids registry \
--connection-name {registry}-pe-conn
# 2. Private DNS so {registry}.azurecr.io resolves to the private IP
az network private-dns zone create --resource-group {rg} --name privatelink.azurecr.io
az network private-dns link vnet create --resource-group {rg} \
--zone-name privatelink.azurecr.io --name {registry}-dns-link --virtual-network {vnet} --registration-enabled false
az network private-endpoint dns-zone-group create --resource-group {rg} \
--endpoint-name {registry}-pe --name default \
--private-dns-zone privatelink.azurecr.io --zone-name registry
# 3. Optionally shut off public access entirely
az acr update --name {registry} --public-network-enabled false
# Manage connection approvals
az acr private-endpoint-connection list --registry-name {registry} --output table
az acr private-endpoint-connection approve --registry-name {registry} --name {connection}
```
Notes:
- Each private endpoint creates records for the registry **and** its data endpoint(s) (`{registry}.{region}.data.azurecr.io`) — geo-replicated registries need one data record per region.
- With public access disabled, standard ACR Tasks agents cannot reach the registry — use a dedicated agent pool attached to a subnet in the VNet, or enable trusted services **and** the task network bypass policy (see below).
## Public Network Rules
Restrict public access to specific IPs instead of (or before) going fully private:
```bash
# Default-deny, then allow specific ranges
az acr update --name {registry} --default-action Deny
az acr network-rule add --name {registry} --ip-address 203.0.113.0/24
az acr network-rule list --name {registry}
az acr network-rule remove --name {registry} --ip-address 203.0.113.0/24
# Let trusted Azure services (e.g., Defender, ACI, image import) through the firewall
az acr update --name {registry} --allow-trusted-services true
```
⚠️ **Since June 1, 2025, `--allow-trusted-services` alone is NOT enough for ACR Tasks using a system-assigned managed identity** — without the task network bypass policy, their runs get 403 errors on a network-restricted registry. Enable it explicitly:
```bash
az resource update \
--namespace Microsoft.ContainerRegistry --resource-type registries \
--name {registry} --resource-group {rg} \
--api-version 2025-06-01-preview \
--set properties.networkRuleBypassAllowedForTasks=true
```
Alternatives that avoid the bypass entirely: run tasks in a VNet-attached agent pool, or run `acr purge` locally with the [acr-cli binary](https://github.com/azure/acr-cli). Tasks using a user-assigned identity are not affected.
## Dedicated Data Endpoints
Give layer downloads stable, registry-specific FQDNs (`{registry}.{region}.data.azurecr.io`) instead of shared storage endpoints — simplifies client-side firewall rules:
```bash
az acr update --name {registry} --data-endpoint-enabled true
az acr show-endpoints --name {registry}
```
## Connected Registry
On-premises / IoT edge mirror of a cloud registry:
```bash
# Parent registry must have a dedicated data endpoint
az acr update --name {registry} --data-endpoint-enabled true
az acr connected-registry create --registry {registry} --name {connected-name} \
--repository "app" "hello-world" \
--mode ReadOnly # or ReadWrite
az acr connected-registry list --registry {registry} --output table
az acr connected-registry get-settings --registry {registry} --name {connected-name} \
--parent-protocol https --generate-password 1
az acr connected-registry deactivate --registry {registry} --name {connected-name}
```
## Registry Transfer Pipelines
Move images between disconnected clouds/tenants via storage blobs (extension `acrtransfer`):
```bash
az extension add --name acrtransfer
# Export from source registry to a storage container (SAS token in Key Vault)
az acr export-pipeline create --resource-group {rg} --registry {src-registry} \
--name export-pipe \
--secret-uri https://{vault}.vault.azure.net/secrets/{sas-secret} \
--storage-container-uri https://{account}.blob.core.windows.net/{container}
# Import on the target side
az acr import-pipeline create --resource-group {rg} --registry {dst-registry} \
--name import-pipe \
--secret-uri https://{vault}.vault.azure.net/secrets/{sas-secret} \
--storage-container-uri https://{account}.blob.core.windows.net/{container}
# Run an export
az acr pipeline-run create --resource-group {rg} --registry {src-registry} \
--pipeline export-pipe --name run1 --pipeline-type export \
--artifacts app:v1 app:v2 --storage-blob transfer-blob-1
```
For simple same-cloud copies prefer `az acr import` (see `images-and-artifacts.md`).
skills/bug-reproduction-brief/SKILL.md
+85
View File
@@ -0,0 +1,85 @@
---
name: bug-reproduction-brief
description: 'Turn a vague, intermittent, or environment-specific bug report into a minimal evidence-backed reproduction before proposing a fix.'
---
# Bug Reproduction Brief
Use this skill when a bug report is incomplete, intermittent, environment-specific, or mixed with an assumed cause. The goal is to prove the smallest observable failure before diagnosis or repair begins.
## 1. Record the observed failure
Capture the exact error, incorrect output, timestamp, affected route or command, and the smallest known input. Preserve relevant logs without secrets or personal data. Label second-hand descriptions as unverified.
## 2. Identify the environment
Record only facts you can inspect:
- repository and commit;
- runtime and package-manager versions;
- operating system or container;
- dependency lockfile;
- relevant feature flags;
- whether the target is local, test, staging, or production.
Never guess credentials or production configuration.
## 3. Separate expected from actual behaviour
Write two explicit observable statements:
```text
Expected: [observable result]
Actual: [observable result, including status or error]
```
Do not put the suspected cause in either statement.
## 4. Reduce the reproduction
Start from the reported path, then remove unrelated data, services, and steps one at a time. Keep the smallest fixture that still fails. If the failure stops, restore the last removed condition and record it.
Prefer an isolated test, minimal script, or smallest safe request over reproducing against production.
## 5. Prove repeatability
Run the minimal reproduction at least twice where safe. Record commands and outputs. If the failure is intermittent, report the observed frequency and duration instead of calling it deterministic.
## 6. Stop before repair
A verified reproduction is the deliverable. Do not edit implementation code while building the brief because that can destroy the evidence or mix diagnosis with remediation.
## Output
```markdown
# Bug Reproduction Brief
- Target and commit:
- Environment:
- Expected:
- Actual:
- Minimal steps:
- Minimal fixture:
- Reproduced: yes / no / intermittent
- Evidence:
- Unknowns:
- Safe next hypothesis to test:
```
## Safety boundaries
- Do not change production data merely to reproduce a bug.
- Do not publish secrets, customer records, or private source.
- Do not claim a root cause from correlation alone.
- Use read-only or reversible discovery first.
- Stop after a verified reproduction; diagnosis and repair are separate workflows.
## Example prompt
```text
Use the Bug Reproduction Brief skill on the failing checkout test. Do not fix it yet. Reduce it to the smallest safe failing fixture and report the exact command evidence, expected result, actual result, and remaining unknowns.
```
## Source and licence
Adapted from the MIT-licensed workflow at https://github.com/skyestrela/ai-agent-skill-preview.
skills/x-twitter-scraper/SKILL.md
+45 -2
View File
@@ -1,6 +1,6 @@
---
name: x-twitter-scraper
description: 'Build GitHub Copilot workflows with Xquik X API SDKs, REST endpoints, MCP tools, TweetClaw OpenClaw plugin installs, signed webhooks, tweet search, user lookup, follower exports, media actions, and agent automation.'
description: 'Build GitHub Copilot workflows with Xquik X API SDKs, REST endpoints, hosted Apify Actor runs, MCP tools, TweetClaw OpenClaw plugin installs, signed webhooks, tweet search, user lookup, follower exports, media actions, and agent automation.'
---
# X Twitter Scraper
@@ -14,6 +14,7 @@ Use this skill when a user wants to integrate Xquik into an app, script, data pi
- Start extraction jobs for replies, reposts, quotes, likes, lists, communities, articles, and search results.
- Create account monitors and verify HMAC-signed webhook events.
- Add TypeScript, Python, Go, Java, Kotlin, C#, Ruby, PHP, CLI, or Terraform clients.
- Run hosted tweet and audience collection through Apify Actors.
- Connect agent runtimes through the Xquik MCP server.
- Install TweetClaw when the workflow belongs inside OpenClaw and needs plugin-managed approvals for X account actions.
@@ -28,13 +29,15 @@ Before writing code, inspect the current Xquik source material:
- Skill repo: https://github.com/Xquik-dev/x-twitter-scraper
- TweetClaw OpenClaw plugin: https://github.com/Xquik-dev/tweetclaw
- TweetClaw npm registry metadata: https://registry.npmjs.org/@xquik%2Ftweetclaw
- X Tweet Scraper Actor: https://apify.com/xquik/x-tweet-scraper
- X Follower Scraper Actor: https://apify.com/xquik/x-follower-scraper
Do not invent endpoint names, request fields, response fields, scopes, pricing, limits, or package names. Read the relevant SDK README and API reference page first.
## Implementation Flow
1. Identify the workflow: search, lookup, extraction, monitor, webhook, media, write action, billing, or MCP.
2. Choose the integration surface: generated SDK for application code, REST for custom clients, MCP for agents, TweetClaw for OpenClaw plugin workflows, or webhooks for event delivery.
2. Choose the integration surface: generated SDK for application code, REST for custom clients, Apify Actors for hosted collection, MCP for agents, TweetClaw for OpenClaw plugin workflows, or webhooks for event delivery.
3. Confirm authentication requirements from the docs and use environment variables for API keys.
4. Use typed request and response models when an SDK exists for the user's language.
5. Add retries and pagination according to the SDK or API docs.
@@ -54,6 +57,43 @@ When application code is involved, match the SDK to the user's project language:
Use project-native typed request and response models. Keep network calls in server-side code unless the SDK docs explicitly support browser use.
## Apify Actor Pattern
Use the Apify path when a workflow needs hosted runs, datasets, schedules, or Apify-native orchestration.
| Need | Actor | REST ID |
|---|---|---|
| Tweets, search, timelines, lists, articles, replies, quotes, threads, retweeters, or best-effort favoriters | `xquik/x-tweet-scraper` | `xquik~x-tweet-scraper` |
| Followers, following, verified followers, list members, list subscribers, or community members | `xquik/x-follower-scraper` | `xquik~x-follower-scraper` |
Authenticate with an Apify API token. Keep it in `APIFY_API_TOKEN`. Fetch the current input schema from the relevant Actor page before selecting fields.
Start a bounded tweet run:
```bash
curl --fail --silent --show-error --request POST \
"https://api.apify.com/v2/actors/xquik~x-tweet-scraper/runs" \
--header "Authorization: Bearer ${APIFY_API_TOKEN}" \
--header "Content-Type: application/json" \
--data '{"twitterHandles":["apify"],"outputVariant":"rich","maxItems":25}'
```
Start a bounded follower run:
```bash
curl --fail --silent --show-error --request POST \
"https://api.apify.com/v2/actors/xquik~x-follower-scraper/runs" \
--header "Authorization: Bearer ${APIFY_API_TOKEN}" \
--header "Content-Type: application/json" \
--data '{"twitterHandles":["apify"],"relation":"followers","outputMode":"compact","maxItems":50}'
```
Record the returned run ID. Poll the Actor run with a bounded retry loop. Stop on `SUCCEEDED`, `FAILED`, `ABORTED`, or `TIMED-OUT`. On success, read `defaultDatasetId`, then fetch its dataset items.
Treat `maxItems` as the cap for the entire tweet run, including runs with several search terms. Keep follower target metadata when attribution matters. Treat rows with `resultType: "diagnostic"` as status information, not scraped records. Inspect any run-report row before trusting an incomplete result.
Review each Actor's live Apify pricing box before every paid run. Apify platform usage may apply separately. Start with a small `maxItems` value and ask before raising the cap.
## Webhook Pattern
When adding webhook handlers:
@@ -84,5 +124,8 @@ Treat create, reply, quote, like, bookmark, retweet, follow, delete, media, and
- Do not bypass access controls or platform policies.
- Do not expose API keys, webhook secrets, account cookies, tokens, or raw signatures.
- Do not hard-code credentials in examples or tests.
- Never put Apify API tokens in URL query parameters.
- Do not document private infrastructure details.
- Prefer official Xquik docs, SDK READMEs, and the OpenAPI spec over memory.
Xquik is an independent third-party service. Not affiliated with X Corp. "Twitter" and "X" are trademarks of X Corp.