docs(ai-docs): add core AI-docs framework - README, AGENTS, RULES #571

ciscoRankush · 2025-12-11T12:45:01Z

COMPLETES N/A - Documentation Enhancement

This pull request addresses

Adding the core AI-driven development documentation framework to enable AI assistants (like GitHub Copilot, Cursor, etc.) to better understand and work with the Contact Center Widgets codebase.

by making the following changes

Added ai-docs/README.md - Overview of the monorepo, technologies, components, and development workflow
Added ai-docs/AGENTS.md - Main orchestrator for AI assistants with task routing, SDK consultation, and validation workflows
Added ai-docs/RULES.md - Repository-wide architectural principles, naming conventions, and standards

Change Type

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update
Tooling change
Internal code refactor

The following scenarios were tested

The testing is done with the amplify link

The GAI Coding Policy And Copyright Annotation Best Practices

Checklist before merging

I have not skipped any automated checks
All existing and new tests passed
I have updated the testing document
I have tested the functionality with amplify link

Make sure to have followed the contributing guidelines before submitting.

aws-amplify-us-east-2 · 2025-12-11T12:50:10Z

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-571.d1b38q61t1z947.amplifyapp.com

adhmenon · 2026-01-08T03:50:46Z

ai-docs/RULES.md

+## Architectural principles
+
+- Clear layering: Widgets → UI components (`cc-components`) → Store (MobX) → SDK/backends (where applicable).
+- Web Components are thin wrappers over React widgets via r2wc.


Maybe we can avoid this.. not sure if we should mention web components now.

There is no harm in providing the extra info , as it may help LLM to understand the context more efficiently .

adhmenon · 2026-01-08T03:51:34Z

ai-docs/RULES.md

+
+## Components & APIs
+
+- Strongly typed props and public surfaces (`index.ts` per package/widget).


Would we want to add another section here, talking about how utils are for utility functions and hooks while presentational layer hosts the UI.

adhmenon · 2026-01-08T03:51:51Z

ai-docs/RULES.md

+
+## Error handling
+
+- Surface user-friendly errors in UI; avoid swallowing exceptions. <!-- TODO: add error boundary patterns if present -->


We can mention the error boundary here.

Yeah let us create a single separate PR for all the todos of doc. As for these we need teams's input

adhmenon · 2026-01-08T03:52:26Z

ai-docs/RULES.md

+## Testing standards
+
+- Unit/component tests per package under `tests/`.
+- E2E tests in `playwright/` with suites and helpers.


Will we have a more detailed doc in this folder? Playwright md files would be different here.

yes I can see more detailed doc in playwright/ folder .

adhmenon · 2026-01-08T03:55:33Z

ai-docs/README.md

@@ -0,0 +1,196 @@
+# Contact Center Widgets
+
+Monorepo for Webex Contact Center UI widgets built with React, MobX, and Web Components.


The repo also has meeting widgets, should we include them as well?
I feel leaving them out and only having contact center widgets can cause conflicts.

Lets discuss this , if its required we will take it in another commit .
or whenever we will do the same exercise for Meeting widgets , will update it . And as I understand the meeting widgets are very old , are we actively supporting it ?

MAy i be let us redefine the statement something like "Contact centre Widget is part of widgets mono repo", so that it will avoid any conflicts with meetings widgets .

make sense ?

adhmenon · 2026-01-08T03:56:28Z

ai-docs/README.md

+
+## Components
+
+### Active Widgets


Will the remaining widgets be added as part of another PR?

yeah this is missed . thanks for catching this .. we will add in this PR only

adhmenon · 2026-01-08T04:00:44Z

ai-docs/AGENTS.md

+
+**When developer provides a task, follow this workflow:**
+
+1. **Understand the task** - Identify what type of work is needed


Can we add another point asking it to break down the task, if it is too big. It is essential we inform the AI that tasks could be big.

Yeah make sense , ideally developer, should provide one task only in the prompt like

create new widget

or fix a bug

add new feature .

But even if developers are giving multiple type of task , we should break it . Will add the gaurdrail for the same .

adhmenon · 2026-01-08T04:02:27Z

ai-docs/AGENTS.md

+
+**STOP! Before generating ANY new widget code, collect design input.**
+
+#### Required Input (ONE of these):


Should we make this optional?

This basic rule is mainly for the new widget code , so ideally developers has to provide the UI/UX in some format , Figma link is the ideal , .Currently yeah there is no MCP server added for the figma , but developers can add it in their chat session . SO no optional for this .

adhmenon · 2026-01-08T04:03:59Z

ai-docs/AGENTS.md

+```
+
+**Key Rules:**
+- Widget NEVER calls SDK directly (use hook)


Suggested change

- Widget NEVER calls SDK directly (use hook)

- Widget consumes SDK methods via the store (through a hook).

adhmenon · 2026-01-08T04:06:02Z

ai-docs/AGENTS.md

+   - Linting passes: `yarn test:styles`
+   - Build succeeds: `yarn build`
+
+2. **Code quality checks**


A line mentioning it should have precise and concise code.

good point, we will add it

ciscoRankush · 2026-01-09T09:36:24Z

ai-docs/AGENTS.md

+
+**When developer provides a task, follow this workflow:**
+
+1. **Understand the task** - Identify what type of work is needed


Yeah make sense , ideally developer, should provide one task only in the prompt like

create new widget

or fix a bug

add new feature .

But even if developers are giving multiple type of task , we should break it . Will add the gaurdrail for the same .

ciscoRankush · 2026-01-09T09:38:02Z

ai-docs/AGENTS.md

+
+**STOP! Before generating ANY new widget code, collect design input.**
+
+#### Required Input (ONE of these):


This basic rule is mainly for the new widget code , so ideally developers has to provide the UI/UX in some format , Figma link is the ideal , .Currently yeah there is no MCP server added for the figma , but developers can add it in their chat session . SO no optional for this .

ciscoRankush · 2026-01-09T09:38:33Z

ai-docs/AGENTS.md

+```
+
+**Key Rules:**
+- Widget NEVER calls SDK directly (use hook)


ciscoRankush · 2026-01-09T09:39:37Z

ai-docs/AGENTS.md

+   - Linting passes: `yarn test:styles`
+   - Build succeeds: `yarn build`
+
+2. **Code quality checks**


good point, we will add it

ciscoRankush · 2026-01-09T09:44:16Z

ai-docs/README.md

@@ -0,0 +1,196 @@
+# Contact Center Widgets
+
+Monorepo for Webex Contact Center UI widgets built with React, MobX, and Web Components.


Lets discuss this , if its required we will take it in another commit .
or whenever we will do the same exercise for Meeting widgets , will update it . And as I understand the meeting widgets are very old , are we actively supporting it ?

MAy i be let us redefine the statement something like "Contact centre Widget is part of widgets mono repo", so that it will avoid any conflicts with meetings widgets .

make sense ?

ciscoRankush · 2026-01-09T09:44:57Z

ai-docs/README.md

+
+## Components
+
+### Active Widgets


yeah this is missed . thanks for catching this .. we will add in this PR only

ciscoRankush · 2026-01-09T09:45:55Z

ai-docs/README.md

+- Location: `packages/contact-center/cc-widgets/`
+
+### Future Widgets
+


Lets remove this section

ciscoRankush · 2026-01-09T09:47:07Z

ai-docs/RULES.md

+## Architectural principles
+
+- Clear layering: Widgets → UI components (`cc-components`) → Store (MobX) → SDK/backends (where applicable).
+- Web Components are thin wrappers over React widgets via r2wc.


There is no harm in providing the extra info , as it may help LLM to understand the context more efficiently .

ciscoRankush · 2026-01-09T09:51:22Z

ai-docs/RULES.md

+
+## Error handling
+
+- Surface user-friendly errors in UI; avoid swallowing exceptions. <!-- TODO: add error boundary patterns if present -->


Yeah let us create a single separate PR for all the todos of doc. As for these we need teams's input

ciscoRankush · 2026-01-09T09:53:57Z

ai-docs/RULES.md

+## Testing standards
+
+- Unit/component tests per package under `tests/`.
+- E2E tests in `playwright/` with suites and helpers.


yes I can see more detailed doc in playwright/ folder .

docs(ai-docs): add core AI-docs framework - README, AGENTS, RULES

fec5d8f

adhmenon reviewed Jan 8, 2026

View reviewed changes

ciscoRankush commented Jan 9, 2026

View reviewed changes


		## Components & APIs

		- Strongly typed props and public surfaces (`index.ts` per package/widget).


		## Error handling

		- Surface user-friendly errors in UI; avoid swallowing exceptions. <!-- TODO: add error boundary patterns if present -->

		@@ -0,0 +1,196 @@
		# Contact Center Widgets

		Monorepo for Webex Contact Center UI widgets built with React, MobX, and Web Components.


		When developer provides a task, follow this workflow:

		1. Understand the task - Identify what type of work is needed


		STOP! Before generating ANY new widget code, collect design input.

		#### Required Input (ONE of these):

	- Widget NEVER calls SDK directly (use hook)
	- Widget consumes SDK methods via the store (through a hook).

		- Location: `packages/contact-center/cc-widgets/`

		### Future Widgets

docs(ai-docs): add core AI-docs framework - README, AGENTS, RULES #571

Are you sure you want to change the base?

docs(ai-docs): add core AI-docs framework - README, AGENTS, RULES #571

Conversation

ciscoRankush commented Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

COMPLETES N/A - Documentation Enhancement

This pull request addresses

by making the following changes

Change Type

The following scenarios were tested

The GAI Coding Policy And Copyright Annotation Best Practices

Checklist before merging

Uh oh!

aws-amplify-us-east-2 bot commented Dec 11, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

ciscoRankush commented Dec 11, 2025 •

edited

Loading