docs(contact-center): add SDD templates for new service creation#4734
docs(contact-center): add SDD templates for new service creation#4734ciscoRankush wants to merge 3 commits intowebex:task-refactorfrom
Conversation
Add Spec-Driven Development templates for creating new services: - 00-master.md — Orchestrator with workflow overview - 01-pre-questions.md — STOP gate with interrogative questions, MANDATORY/OPTIONAL labels, event contract, spec summary - 02-code-generation.md — Service class generation patterns - 03-integration.md — Registration and exports in cc.ts - 04-test-generation.md — Unit test file generation - 05-validation.md — Quality checklist with correct workspace commands Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Shreyas281299
added
the
validated
Kesari3008
left a comment
Kesari3008
left a comment
There was a problem hiding this comment.
Generic comment for new service creation: Everywhere we are assuming that this new service will be created at cc level. What if that's not the case ?
What if we need to expose a service under task folder ?
| @@ -0,0 +1,107 @@ | |||
| # New Service Creation - Master Template | |||
|
|
|||
| > **Purpose**: Orchestrator for creating new services (like AddressBook, EntryPoint, Queue). | |||
There was a problem hiding this comment.
I feel this can be misleading as we are giving only helper classes as refernce for new services, when we are going to treat agents folder, core folder, config folder also as separate services so maybe we can update this purpose to be more accurate
There was a problem hiding this comment.
Changed as discussed over call
|
|
||
| You can land on this template from: | ||
| - direct "create new service" requests | ||
| - "add feature" requests after placement triage determines the feature should be a standalone service/module |
There was a problem hiding this comment.
here it says placement triage and below feature triage, we should refer to it with same name
| ## Workflow Overview | ||
|
|
||
| ``` | ||
| Step 1: Requirements → Step 2: Code Generation → Step 3: Integration → Step 4: Tests → Step 5: Validation |
There was a problem hiding this comment.
This can be represented as left to right flowchart or a block diagram maybe
There was a problem hiding this comment.
this is more machine readable statement , thats why kept like that
|
|
||
| Create: | ||
| - Service class file (`src/services/ServiceName.ts`) | ||
| - Type definitions (in service file or `types.ts`) |
There was a problem hiding this comment.
This should be updated to say corresponding folder's types.ts
|
|
||
| Integrate: | ||
| - Initialize in `cc.ts` constructor | ||
| - Expose via `cc.serviceName` if public |
There was a problem hiding this comment.
We are saying expose via cc.serviceName if public but have we mentioned anywhere how it knows what's public ?
| ## Patterns to Load | ||
|
|
||
| Before generating code, read: | ||
| 1. [`../../patterns/typescript-patterns.md`](../../patterns/typescript-patterns.md) - Type conventions |
There was a problem hiding this comment.
This will need update once we have patterns updated
| - If YES: "Which specific fields?" (e.g., `addressBookId`, `teamIds`) | ||
| - If NO: note "No profile dependency" | ||
|
|
||
| 6. **"Does this service need to process WebSocket events?"** |
There was a problem hiding this comment.
This point and 4th point are common so can be clubbed
| import LoggerProxy from '../logger-proxy'; | ||
|
|
||
| /** | ||
| * Service name and module identifier for logging |
There was a problem hiding this comment.
How we have added a heading that type definitions need to be created, we should add similar heading here for constnst also. And we should add a link here saying type definitions in types.ts file and contacnts and enums in contactnts. ts file. If these files are already existing then update there else create new files for this new service
| // throw new Error('Dependency ID not available. Ensure agent is logged in.'); | ||
| // } | ||
|
|
||
| const queryParams = new URLSearchParams(); |
There was a problem hiding this comment.
This code reference seems vers specific, can we not make it generic since it say service template
|
|
||
| --- | ||
|
|
||
| ## Code Quality Checklist |
There was a problem hiding this comment.
Do we not need to mention about metric in checklist
Shreyas281299
left a comment
Shreyas281299
left a comment
There was a problem hiding this comment.
I feel Priya has covered everything. I dont have any other comments.
…vice templates Apply reviewer feedback from Kesari3008 and validate against actual codebase: - Broaden 00-master.md purpose to cover top-level, sub-module, and internal services - Add placement Q3 to 01-pre-questions.md with folder-based/single-file/sub-module options - Merge duplicate event/WebSocket questions into unified Q5 - Rewrite 02-code-generation.md with placement-branched file structures, types, constants - Add MetricsManager and getErrorDetails as mandatory patterns in code templates - Rewrite 03-integration.md with Path A (folder-based), Path B (single-file), Path C (sub-module) - Distinguish AQM (Services singleton) vs non-AQM (cc.ts direct) integration - Add metrics section and placement-aware checklists to 05-validation.md Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…ation template Constants exist at multiple levels (root, services, metrics, config, service-specific). Before creating any new constant, the template now requires searching the full hierarchy to prevent duplicates and ensure correct placement. A new constants.ts file is only created when the service is folder-based, no file exists yet, and constants are service-specific. Validation checklist updated to enforce these checks. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
3 participants
COMPLETES #SPARK-775697
This pull request addresses
AI agents need structured templates to guide new service creation in the @webex/contact-center SDK, ensuring they gather complete requirements before writing code.
by making the following changes
Adds
ai-docs/templates/new-service/with 6 template files:00-master.md— Orchestrator with workflow overview and pattern links01-pre-questions.md— STOP gate with 9 interrogative questions, MANDATORY/OPTIONAL labels, event contract table, completion gate, and spec summary template02-code-generation.md— Service class generation patterns03-integration.md— Registration and exports in cc.ts04-test-generation.md— Unit test file generation05-validation.md— Quality checklist with correct workspace commands (test:styles, test:unit, build:src)Change Type
The following scenarios were tested
The GAI Coding Policy And Copyright Annotation Best Practices
I certified that