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 3 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 👍 / 👎.
1 participant
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