Skip to content

docs(ai-docs): update AGENTS.md (AI agent constraints and workflow) #618

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ciscoRankush wants to merge 2 commits into
base: next
Choose a base branch
from
Open

docs(ai-docs): update AGENTS.md (AI agent constraints and workflow) #618

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f6ed9c0
docs: update AGENTS.md
Feb 9, 2026
74c9e4f
Merge branch 'next' into updateAIDocsConstraints
Shreyas281299 Feb 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 49 additions & 18 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@

This is the main orchestrator for AI assistants working on this repository. It routes you to the correct templates and documentation based on the developer's task.

**For every developer request:** (1) Identify task type (A–E below). (2) If the work is in an existing package or widget, load that scope's ai-docs (see [Package and widget ai-docs reference](#package-and-widget-ai-docs-reference)) and follow its AGENTS.md. (3) Open the template for that type and complete its mandatory pre-steps (see [Mandatory pre-steps by task type](#mandatory-pre-steps-by-task-type)). (4) Then follow the rest of this guide and the template.

---

## Quick Start
Expand All @@ -13,9 +15,11 @@ This is the main orchestrator for AI assistants working on this repository. It r
1. **Understand the task** - Identify what type of work is needed
2. **Break down large or multi-part tasks** - If the prompt mixes multiple tasks (for example, "create new widget" **and** "fix a bug" or "add a feature"), or the task is very large, split it into smaller, clearly scoped subtasks and handle them one by one
3. **Route to appropriate template** - Use modular templates for guidance
4. **Generate/fix code** - Follow established patterns
5. **Update documentation** - Keep ai-docs in sync with code changes
6. **Ask for review** - Confirm completion with developer
4. **Load package/widget ai-docs when working in that scope** - If fixing, generating, or enhancing code in an existing package or widget, read that scope's [ai-docs/AGENTS.md and ARCHITECTURE.md](#package-and-widget-ai-docs-reference) and follow them (see CRITICAL RULES rule 3).
5. **Complete that template's mandatory pre-step section** - See [Mandatory pre-steps by task type](#mandatory-pre-steps-by-task-type) in CRITICAL RULES. Do not generate code until pre-steps are done or the developer explicitly waives them.
6. **Generate/fix code** - Follow established patterns
7. **Update documentation** - Keep ai-docs in sync with code changes
8. **Ask for review** - Confirm completion with developer

---

Expand Down Expand Up @@ -50,8 +54,8 @@ If the developer's message contains multiple distinct task types (for example, "

**E. Understanding Architecture**
- Developer needs to understand how something works
- **Read:** Package's `ai-docs/AGENTS.md` (usage) and `ai-docs/ARCHITECTURE.md` (technical details)
- **Available for:** station-login, user-state, store, cc-components, cc-widgets, ui-logging, test-fixtures
- **Read:** That scope's `ai-docs/AGENTS.md` (usage) and `ai-docs/ARCHITECTURE.md` (technical details); use [Package and widget ai-docs reference](#package-and-widget-ai-docs-reference) to find the path.
- **Available for:** station-login, user-state, store, cc-components, cc-widgets, ui-logging, test-fixtures; for task package use per-widget ai-docs (CallControl, IncomingTask, OutdialCall, TaskList).

---

Expand Down Expand Up @@ -148,6 +152,24 @@ Once provided, I'll analyze it and generate the widget accordingly.

**DO NOT proceed without design input.**

### 3. Use Package/Widget ai-docs When Working in That Scope

When fixing, generating, or enhancing code in a package or widget, you MUST read and follow that scope's `ai-docs/AGENTS.md` (and `ai-docs/ARCHITECTURE.md` where available). See [Package and widget ai-docs reference](#package-and-widget-ai-docs-reference) in Step 2. The root AGENTS.md is the orchestrator; each package/widget AGENTS.md is the authoritative reference for that scope—use both.

### 4. Complete Template Pre-Steps Before Code

Before generating or changing any code, you MUST complete the **pre-step section** of the template for the task type (see table below). Either fill it from the developer's message and confirm, or ask the developer for missing items. Do not proceed to implementation steps until pre-steps are done or the developer explicitly asks to skip them.

#### Mandatory pre-steps by task type (Rule 4)

| Task type | Template | Mandatory pre-step (complete before code) |
| --------- | -------- | ----------------------------------------- |
| **A. Create New Widget** | [new-widget/00-master.md](./ai-docs/templates/new-widget/00-master.md) | Design input + [01-pre-questions.md](./ai-docs/templates/new-widget/01-pre-questions.md) (widget name, 4 technical inputs) |
| **B. Fix Bug** | [existing-widget/bug-fix.md](./ai-docs/templates/existing-widget/bug-fix.md) | [Pre-Fix Questions](./ai-docs/templates/existing-widget/bug-fix.md) (bug info, scope, impact, existing tests) |
| **C. Add Feature** | [existing-widget/feature-enhancement.md](./ai-docs/templates/existing-widget/feature-enhancement.md) | [Pre-Enhancement Questions](./ai-docs/templates/existing-widget/feature-enhancement.md) (feature info, requirements, compatibility, design input) |
| **D. Documentation only** | documentation templates | Optional: confirm scope with developer (no code change) |
| **E. Understanding** | Package ai-docs | None (read-only) |

---

## Step 2: Load Context
Expand All @@ -162,9 +184,26 @@ Once provided, I'll analyze it and generate the widget accordingly.
- [web-component-patterns.md](./ai-docs/patterns/web-component-patterns.md) - r2wc patterns
- [testing-patterns.md](./ai-docs/patterns/testing-patterns.md) - Jest, RTL, Playwright

2. **Package documentation** - If working on existing widget
- `packages/contact-center/{widget-name}/ai-docs/AGENTS.md` - Usage and API
- `packages/contact-center/{widget-name}/ai-docs/ARCHITECTURE.md` - Technical details
2. **Package/widget ai-docs (mandatory when working in that scope)**
When fixing, generating, or enhancing code in a package or widget, you **MUST** read that scope's `ai-docs/AGENTS.md` (and `ARCHITECTURE.md` where listed) and follow its instructions. The root AGENTS.md orchestrates; package/widget AGENTS.md is the authoritative reference for that scope. Use the table below to find the right path.

#### Package and widget ai-docs reference

| Scope you're working on | AGENTS.md | ARCHITECTURE.md |
| ----------------------- | --------- | --------------- |
| **station-login** | [packages/contact-center/station-login/ai-docs/AGENTS.md](packages/contact-center/station-login/ai-docs/AGENTS.md) | Same folder |
| **user-state** | [packages/contact-center/user-state/ai-docs/AGENTS.md](packages/contact-center/user-state/ai-docs/AGENTS.md) | Same folder |
| **task – CallControl** | [packages/contact-center/task/ai-docs/widgets/CallControl/AGENTS.md](packages/contact-center/task/ai-docs/widgets/CallControl/AGENTS.md) | Same folder |
| **task – IncomingTask** | [packages/contact-center/task/ai-docs/widgets/IncomingTask/AGENTS.md](packages/contact-center/task/ai-docs/widgets/IncomingTask/AGENTS.md) | Same folder |
| **task – OutdialCall** | [packages/contact-center/task/ai-docs/widgets/OutdialCall/AGENTS.md](packages/contact-center/task/ai-docs/widgets/OutdialCall/AGENTS.md) | Same folder |
| **task – TaskList** | [packages/contact-center/task/ai-docs/widgets/TaskList/AGENTS.md](packages/contact-center/task/ai-docs/widgets/TaskList/AGENTS.md) | Same folder |
| **store** | [packages/contact-center/store/ai-docs/AGENTS.md](packages/contact-center/store/ai-docs/AGENTS.md) | Same folder |
| **cc-components** | [packages/contact-center/cc-components/ai-docs/AGENTS.md](packages/contact-center/cc-components/ai-docs/AGENTS.md) | Same folder |
| **cc-widgets** | [packages/contact-center/cc-widgets/ai-docs/AGENTS.md](packages/contact-center/cc-widgets/ai-docs/AGENTS.md) | Same folder |
| **ui-logging** | [packages/contact-center/ui-logging/ai-docs/AGENTS.md](packages/contact-center/ui-logging/ai-docs/AGENTS.md) | Same folder |
| **samples-cc-react-app** | [widgets-samples/cc/samples-cc-react-app/ai-docs/AGENTS.md](widgets-samples/cc/samples-cc-react-app/ai-docs/AGENTS.md) | Same folder if present |

**Task package note:** The task package has multiple widgets (CallControl, IncomingTask, OutdialCall, TaskList). When working on one of them, use that widget's ai-docs path above, not a generic task path.

### Conditionally Read

Expand All @@ -173,16 +212,6 @@ Once provided, I'll analyze it and generate the widget accordingly.
- Find available methods, events, types
- Check method signatures before using

**If modifying store:**
- Read: `packages/contact-center/store/ai-docs/AGENTS.md`
- Read: `packages/contact-center/store/ai-docs/ARCHITECTURE.md`

**If creating/using components:**
- Read: `packages/contact-center/cc-components/ai-docs/AGENTS.md`

**If working with metrics/logging:**
- Read: `packages/contact-center/ui-logging/ai-docs/AGENTS.md`

---

## Step 3: SDK API Consultation (Before Code Generation)
Expand Down Expand Up @@ -303,6 +332,8 @@ SDK (Contact Center API)

**Follow the template you were routed to in Step 1**

You must have already completed that template's pre-step section (Pre-Enhancement Questions, Pre-Fix Questions, or 01-pre-questions as applicable); if not, do that first.

**During code generation:**
1. Follow pattern documentation strictly
2. Reference existing widgets for examples
Expand Down
Loading