docs(ai-docs): migrate to SDLC-Templates component-repo standard#707
docs(ai-docs): migrate to SDLC-Templates component-repo standard#707bhabalan wants to merge 4 commits into
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 👍 / 👎.
2 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