docs(ai-docs): migrate to SDLC-Templates component-repo standard#707
Conversation
Reshape the repo's AI documentation to conform to the SDLC-Templates component-repo standard (library version 0.1.0-draft). Standing docs (repo-level, ai-docs/): - Reshape root AGENTS.md into the agent-entry contract - Add SPEC_INDEX.md (router + module registry), ARCHITECTURE.md - Add RULES, GLOSSARY, SECURITY, CONTRACTS, GETTING_STARTED, REVIEW_CHECKLIST, SERVICE_STATE - Add adr/ and rules/ scaffolds with seed entries Machine source of truth: - .sdd/manifest.json (per-module coverage state, commands, contracts) - .sdd/coverage-policy.defaults.yaml (drift thresholds, coverage bar) - Track .sdd/manifest.json via .gitignore exception Per-module specs (source-local <module>/ai-docs/<module>-spec.md): - store, cc-components, cc-widgets, station-login, user-state, task, ui-logging, test-fixtures, and legacy @webex/widgets Pre-standard per-package AGENTS.md/ARCHITECTURE.md pairs are preserved under ai-docs/_archive/pre-sdlc-migration/ rather than deleted.
|
This pull request is automatically being deployed by Amplify Hosting (learn more). |
Address review findings against the SDLC-Templates component-repo standard (library 0.1.0-draft): - Repoint the broken SDK reference from the nonexistent contact-centre-sdk-apis/contact-center.json to the installed @webex/contact-center type source (dist/types/index.d.ts) across AGENTS, SPEC_INDEX, CONTRACTS, GLOSSARY, store-spec, manifest, templates, and CLAUDE.md. - Register the previously-undocumented cc-digital-channels module: new module spec + manifest/SPEC_INDEX/RULES/AGENTS entries. - Resolve [NEEDS HUMAN INPUT] placeholders (approved_by: pending) across all module specs. - Reconcile contract IDs: task.* -> cc-widgets.*, store's own surface -> store.instance; add ui-logging.* to the contracts catalog; point test-fixtures internal surface at its entry point; fix cc-digital index path. - Migrate ai-docs/patterns/ to the reference-docs standard (add folder README, per-pattern shape, metadata headers) and correct stale legacy claims against real code. - ARCHITECTURE: strip leftover Include-if scaffolding, add WS6 References (N/A) and Dependency/Interaction Topology sections. - Correct the miscited metricsLogger security note; fix nav pointers, promote user-state UI Flow heading, add ADR/rule metadata headers, and record DATA_MODEL N/A in the manifest.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8215ec1bd6
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | SDK API reference (installed `.d.ts`) | `node_modules/@webex/contact-center/dist/types/index.d.ts` | | ||
| | Per-package architecture & agent docs | `packages/contact-center/{pkg}/ai-docs/` | | ||
|
|
||
| When working in a specific package, always read that package's `ai-docs/AGENTS.md` and `ai-docs/ARCHITECTURE.md` first. |
There was a problem hiding this comment.
After this migration, package-level ai-docs/AGENTS.md and ai-docs/ARCHITECTURE.md files were deleted/archived and replaced by <module>-spec.md files routed through ai-docs/SPEC_INDEX.md (rg --files now shows no non-archive package AGENTS/ARCHITECTURE files). In package-scoped Claude workflows this instruction sends the agent to missing files instead of the new specs, so package work starts from stale/nonexistent guidance.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0a48e95ac2
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| |---|---|---|---|---|---|---| | ||
| | `cc-widgets.IncomingTask` | SDK (React component / Web Component) | `IncomingTask` — props: `incomingTask`; callbacks: `onAccepted({task})`, `onRejected({task})` | Render an offered task with accept/decline; notify consumer on accept/reject/RONA | Stable; adding optional props/callbacks = minor | `src/task.types.ts` (`IncomingTaskProps`) | [`CONTRACTS.md`](../../../../ai-docs/CONTRACTS.md) | | ||
| | `cc-widgets.TaskList` | SDK (React component / Web Component) | `TaskList` — props: `hasCampaignPreviewEnabled?`; callbacks: `onTaskAccepted(task)`, `onTaskDeclined(task, reason)`, `onTaskSelected({task, isClicked})` | List concurrent tasks; accept/decline/select | Stable; `hasCampaignPreviewEnabled` defaults true | `src/task.types.ts` (`TaskListProps`) | [`CONTRACTS.md`](../../../../ai-docs/CONTRACTS.md) | | ||
| | `cc-widgets.CallControl` | SDK (React component / Web Component) | `CallControl` — callbacks: `onHoldResume({isHeld,task})`, `onEnd({task})`, `onWrapUp({task,wrapUpReason})`, `onRecordingToggle({isRecording,task})`, `onToggleMute({isMuted,task})`; props: `conferenceEnabled?`, `consultTransferOptions?`, `callControlClassName?`, `callControlConsultClassName?` | Active-call controls for `store.currentTask` | Stable; `conferenceEnabled` defaults `true` | `src/task.types.ts` (`CallControlProps`) | [`CONTRACTS.md`](../../../../ai-docs/CONTRACTS.md) | |
There was a problem hiding this comment.
In the Web Component context this row overstates the public props: I checked packages/contact-center/cc-widgets/src/wc.ts and the r2wc(CallControl, ...) map only declares onHoldResume, onEnd, onWrapUp, and onRecordingToggle (lines 38-45), while onToggleMute, conferenceEnabled, consultTransferOptions, and the class-name props are React-only unless they are added to the r2wc map. Because this spec is the canonical task surface, host apps may try to configure attributes/properties that the registered widget-cc-call-control never declares.
Useful? React with 👍 / 👎.
| ## Public Surface | ||
| | Contract ID | Type | Surface | Purpose | Compatibility / deprecation | Schema / detail link | Root index | | ||
| |---|---|---|---|---|---|---| | ||
| | `cc-widgets.StationLogin` | SDK / Web Component | React component `StationLogin`; mounted in `@webex/cc-widgets` as custom element `widget-cc-station-login` | Agent station login/logout, CC sign-out, profile-option update, multi-login alert | Stable semver; the custom-element tag name and the `profileMode`/`onLogin`/`onLogout`/`onCCSignOut` prop surface are breaking changes | `src/station-login/station-login.types.ts` (`StationLoginProps`), `IStationLoginProps` in `@webex/cc-components` | `../../../../ai-docs/CONTRACTS.md` | |
There was a problem hiding this comment.
This row makes profileMode and onCCSignOut part of the custom-element prop surface, but widget-cc-station-login is registered with only onLogin and onLogout in packages/contact-center/cc-widgets/src/wc.ts lines 31-35; profileMode and onCCSignOut are React props, not declared Web Component props. Host apps following this spec can wire a station-login element that will not receive those values/callbacks as documented.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a3f4efe97f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | cc-widgets.DigitalChannels | `@webex/cc-digital-channels` | `DigitalChannels` | React component; custom element `widget-cc-digital-channels`; no declared props | stable semver | `packages/contact-center/cc-digital-channels/ai-docs/cc-digital-channels-spec.md` | `packages/contact-center/cc-digital-channels/src/index.ts` | | ||
| | cc-widgets.store | `@webex/cc-store` | `store` | MobX singleton (`Store.getInstance()`); `init(options: InitParams, setupEventListeners): Promise<void>`; sole SDK access point via `store.cc.*` | stable semver | `packages/contact-center/store/ai-docs/store-spec.md` | `packages/contact-center/store/src/index.ts:1,4` | | ||
| | store.types | `@webex/cc-store` | Type re-exports (`IContactCenter`, `ITask`, `Profile`, `Team`, `AgentLogin`, `IStore`, `ILogger`, `InitParams`, `IWebex`, `RealTimeTranscriptionData`, plus ~20 more) | TypeScript `type`/`interface` exports describing the SDK-backed domain surface | stable semver; SDK-shaped types track SDK | `@webex/contact-center` types (`node_modules/@webex/contact-center/dist/types/index.d.ts`) (SDK source); `packages/contact-center/store/ai-docs/store-spec.md` | `packages/contact-center/store/src/store.types.ts:334-366` | | ||
| | store.constants | `@webex/cc-store` | Value/enum re-exports (`CC_EVENTS`, `TASK_EVENTS`, `LoginOptions`, `ConsultStatus`, `CAMPAIGN_PREVIEW_OUTBOUND_TYPES`, `DESKTOP`, `EXTENSION`, etc.) | Exported consts/enums for event names and login/consult/campaign domain values | stable semver | `packages/contact-center/store/ai-docs/store-spec.md` | `packages/contact-center/store/src/store.types.ts:368-403` | |
There was a problem hiding this comment.
When consumers use this contract to import store constants, it advertises ConsultStatus, but packages/contact-center/store/src/store.types.ts no longer exports it: the export block contains CC_EVENTS/TASK_EVENTS/LoginOptions/getDefaultUIControls and is immediately followed by the comment that the ConsultStatus enum was removed. Any code or spec generated from this row will try to import a missing symbol from @webex/cc-store; remove it from the contract or document using task.data.consultStatus instead.
Useful? React with 👍 / 👎.
| | `cc-widgets.TaskList` | SDK (React component / Web Component) | `TaskList` — props: `hasCampaignPreviewEnabled?`; callbacks: `onTaskAccepted(task)`, `onTaskDeclined(task, reason)`, `onTaskSelected({task, isClicked})` | List concurrent tasks; accept/decline/select | Stable; `hasCampaignPreviewEnabled` defaults true | `src/task.types.ts` (`TaskListProps`) | [`CONTRACTS.md`](../../../../ai-docs/CONTRACTS.md) | | ||
| | `cc-widgets.CallControl` | SDK (React component / Web Component) | `CallControl` — callbacks: `onHoldResume({isHeld,task})`, `onEnd({task})`, `onWrapUp({task,wrapUpReason})`, `onRecordingToggle({isRecording,task})`, `onToggleMute({isMuted,task})`; props: `conferenceEnabled?`, `consultTransferOptions?`, `callControlClassName?`, `callControlConsultClassName?` | Active-call controls for `store.currentTask` | Stable; `conferenceEnabled` defaults `true` | `src/task.types.ts` (`CallControlProps`) | [`CONTRACTS.md`](../../../../ai-docs/CONTRACTS.md) | | ||
| | `cc-widgets.CallControlCAD` | SDK (React component / Web Component) | `CallControlCAD` — same callbacks/props as `CallControl`; emphasizes `callControlClassName` / `callControlConsultClassName` | CallControl variant styled for a customer-data layout | Stable; same surface as CallControl | `src/task.types.ts` (`CallControlProps`) | [`CONTRACTS.md`](../../../../ai-docs/CONTRACTS.md) | | ||
| | `cc-widgets.OutdialCall` | SDK (React component / Web Component) | `OutdialCall` — props: `isAddressBookEnabled?` (default `true`); no consumer callbacks | Outbound dialpad + ANI selection; disabled when a telephony task is active | Stable | `src/task.types.ts` (`OutdialProps`) | [`CONTRACTS.md`](../../../../ai-docs/CONTRACTS.md) | |
There was a problem hiding this comment.
For Web Component hosts, isAddressBookEnabled is not declared: packages/contact-center/cc-widgets/src/wc.ts wraps Outdial as r2wc(OutdialCall, {}), while the presentational component defaults the prop to true. Host apps following this row can set isAddressBookEnabled={false}/an attribute on <widget-cc-outdial-call> and still get the address book; either mark the prop as React-only or add it to the r2wc prop map.
Useful? React with 👍 / 👎.
mkesavan13
left a comment
mkesavan13
left a comment
There was a problem hiding this comment.
Approving for the sake of merging
Thank you for your contribution! |
3 participants
COMPLETES #N/A — internal documentation/tooling migration (no Jira issue)
This pull request addresses
The repository's AI documentation did not follow the org-wide SDLC-Templates
component-repostandard (library version0.1.0-draft). Docs were spread across per-packageAGENTS.md/ARCHITECTURE.mdpairs with no machine-readable source of truth, no spec router, and no per-module spec format.by making the following changes
Reshaped the repo's AI documentation to conform to the SDLC-Templates
component-repostandard.Standing docs (repo-level,
ai-docs/):AGENTS.mdinto the agent-entry contractSPEC_INDEX.md(router + module registry) andARCHITECTURE.mdRULES,GLOSSARY,SECURITY,CONTRACTS,GETTING_STARTED,REVIEW_CHECKLIST,SERVICE_STATEadr/andrules/scaffolds with seed entriesMachine source of truth (
.sdd/):manifest.json— per-module coverage state, commands, contracts pointers (tracked via a.gitignoreexception)coverage-policy.defaults.yaml— drift thresholds + changed-line coverage barPer-module specs (
<module>/ai-docs/<module>-spec.md) for: store, cc-components, cc-widgets, station-login, user-state, task, ui-logging, test-fixtures, and legacy@webex/widgets.Archived, not deleted: pre-standard per-package
AGENTS.md/ARCHITECTURE.mdpairs are preserved underai-docs/_archive/pre-sdlc-migration/.Change Type
The following scenarios were tested
The GAI Coding Policy And Copyright Annotation Best Practices
Checklist before merging