doc(contact-center): add ai-docs SDD templates for code generation#4722
doc(contact-center): add ai-docs SDD templates for code generation#4722ciscoRankush wants to merge 4 commits intowebex:task-refactorfrom
Conversation
ciscoRankush
changed the title
Shreyas281299
added
the
validated
|
@codex review |
![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: 9d7d180360
ℹ️ 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".
packages/@webex/contact-center/ai-docs/templates/new-service/05-validation.md
Outdated
Show resolved
Hide resolved
Shreyas281299
left a comment
Shreyas281299
left a comment
There was a problem hiding this comment.
Partial Review.
- new-method
- new-service
Above folders are still left to be reviewed
packages/@webex/contact-center/ai-docs/templates/documentation/create-architecture-md.md
Show resolved
Hide resolved
packages/@webex/contact-center/ai-docs/templates/existing-service/bug-fix.md
Show resolved
Hide resolved
packages/@webex/contact-center/ai-docs/templates/existing-service/feature-enhancement.md
Show resolved
Hide resolved
packages/@webex/contact-center/ai-docs/templates/existing-service/feature-enhancement.md
Outdated
Show resolved
Hide resolved
|
@codex review the PR more thoroughly, the PR is to create templating that will be used the AI agents to detect the type of task the user is prompting it to do |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9d7d180360
ℹ️ 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".
Changes based on reviewer feedback on PR webex#4722: - Fix validation commands in all 4 templates to use actual workspace scripts: test:styles, test:unit, build:src - Clarify event contract "Emitted/Received On" field to explicitly ask which object (cc, task, taskManager) the event is emitted/received on Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Changes based on reviewer feedback on PR webex#4722: - Fix validation commands in all 4 templates to use actual workspace scripts: test:styles, test:unit, build:src - Clarify event contract "Emitted/Received On" field to explicitly ask which object (cc, task, taskManager) the event is emitted/received on Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
ciscoRankush
force-pushed
the
SPARK-775697Templates
branch
from
09de84f to
ec7547b
Compare
…tions Add Spec-Driven Development templates for modifying existing services: - existing-service/bug-fix.md — Section A/B workflow with STOP gate, 6 interrogative questions, root-cause gate before implementation - existing-service/feature-enhancement.md — Always-present placement triage, Type F skip-triage support, spec summary gate - documentation/create-agents-md.md — Template for service AGENTS.md - documentation/create-architecture-md.md — Template for ARCHITECTURE.md - templates/README.md — Template index with categories and usage flow Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
ciscoRankush
force-pushed
the
SPARK-775697Templates
branch
from
ec7547b to
9a6c0cd
Compare
…ancement templates - test:styles → test:style (singular, matches package.json) - test -- --testPathPattern → test:unit (consistent with SDK convention) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6bf8f3bac4
ℹ️ About Codex in GitHub
Codex has been enabled to automatically 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 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| ## Related Documentation | ||
|
|
||
| - [ARCHITECTURE.md](ARCHITECTURE.md) - Technical deep-dive | ||
| - [Pattern files](../../../ai-docs/patterns/) - Coding patterns |
There was a problem hiding this comment.
This template is meant to generate service docs under src/services/<service>/ai-docs/AGENTS.md, but the embedded link ../../../ai-docs/patterns/ resolves to src/ai-docs/patterns from that location, not the package-level ai-docs/patterns directory. As a result, every generated AGENTS file will contain a dead “Pattern files” reference, so agents following the docs cannot reach the intended guidance.
Useful? React with 👍 / 👎.
| ### Creating Service Documentation (Task Type E) | ||
| Use: [`documentation/create-agents-md.md`](documentation/create-agents-md.md) |
There was a problem hiding this comment.
The root decision tree defines Type E as read-only architecture understanding (packages/@webex/contact-center/AGENTS.md), but this README labels Type E as “Creating Service Documentation” and routes it to documentation/create-agents-md.md. That mismatch will misroute Type E requests to a doc-generation workflow instead of the intended analysis flow.
Useful? React with 👍 / 👎.
| 4. Present Spec Summary to developer, wait for approval | ||
| | | ||
| v | ||
| 5. If task is "Add Feature", run placement triage (existing vs new service) |
There was a problem hiding this comment.
The usage flow asks for a Spec Summary approval before running feature placement triage, but triage determines whether the work should stay in existing-service/feature-enhancement.md or reroute to new-service/00-master.md. Following this order can produce an approved spec for the wrong scope and then force a post-approval reroute.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9e1ca7a973
ℹ️ About Codex in GitHub
Codex has been enabled to automatically 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 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| ## Usage Examples | ||
|
|
||
| ### [Use Case 1] | ||
| ```typescript |
There was a problem hiding this comment.
The ## AGENTS.md Structure block is opened with ```markdown and then contains an unescaped inner fence at this line, which closes the outer block in standard Markdown renderers. In GitHub/docs rendering, everything after this point is interpreted as live document content instead of the intended literal template, so agents cannot reliably copy the full sample structure.
Useful? React with 👍 / 👎.
|
|
||
| ## File Structure | ||
|
|
||
| ``` |
There was a problem hiding this comment.
The ## ARCHITECTURE.md Structure example starts as a fenced Markdown block, but this inner triple-backtick fence terminates it early. As a result, the rest of the supposed template renders as normal page content rather than a literal snippet, breaking the documentation workflow for anyone trying to copy/paste the generated ARCHITECTURE skeleton.
Useful? React with 👍 / 👎.
| - [ ] Types | ||
| - [ ] Not sure (this is fine — you will investigate) | ||
|
|
||
| 5. **"Are there any error messages or stack traces you can share?"** |
There was a problem hiding this comment.
5th and 6th point here are also being checked under 3rd point's section. Do we need them in both places ?
| Bug fix is complete when: | ||
| 1. Root cause identified and confirmed with developer | ||
| 2. Fix implemented after developer approval | ||
| 3. Regression test added |
There was a problem hiding this comment.
Does it understand what regression test implies here ?
|
|
||
| ### Triage Questions — Always Ask These: | ||
|
|
||
| 1. **"Does this feature fit within the responsibility of an existing service, or does it introduce a new domain/responsibility?"** |
There was a problem hiding this comment.
What happens if any one of these questions are skipped > Or that even possible ?
| })), | ||
| ``` | ||
|
|
||
| ### Plugin Layer (cc.ts) |
There was a problem hiding this comment.
If the new service is being exposed from cc then this would be coprrect but we won't be always exposing public methods from cc so won;t this need change. Same is applicable for other headings as well
|
|
||
| --- | ||
|
|
||
| ## Step 1: Design the Feature |
There was a problem hiding this comment.
What are these steps for, a description or heading would be helpful because before this also we were doing steps and it can get confused with the order
|
|
||
| --- | ||
|
|
||
| ## File Structure |
There was a problem hiding this comment.
We have removed file stucture from architecture.md to Agents.md so probably we can update that
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cf55cc1861
ℹ️ 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".
|
|
||
| Errors are thrown as `Error` with: | ||
| - `message`: Error description | ||
| - `data.reason`: Error reason code |
There was a problem hiding this comment.
This template tells readers to inspect error.data.reason, but SDK errors produced by getErrorDetails store the human-readable reason in error.message and only attach {message, fieldName} to error.data (src/services/core/Utils.ts). If service docs are generated from this template, developers following the documented error-handling pattern will read an undefined field and miss the actual failure reason.
Useful? React with 👍 / 👎.
3 participants
COMPLETES #SPARK-775697
This pull request addresses
AI agents working on the @webex/contact-center SDK need structured code generation templates that enforce a spec-driven workflow — gathering requirements, presenting spec summaries for developer approval, and
following validation checklists before completing work. Without these templates, agents produce inconsistent code that misses SDK patterns like LoggerProxy, MetricsManager, and error handling.
by making the following changes
ai-docs/templates/with 5 template files across 2 categories:F skip-triage support, and spec summary gate
All templates include:
- STOP gates preventing code generation before information gathering
- Interrogative phrasing (questions, not fill-in forms)
- MANDATORY/OPTIONAL labels per section
- Completion gates with checklists
- Spec summary templates requiring developer approval
- Direct clickable links to related files (no vague references)
Change Type
The following scenarios were tested
MANDATORY/OPTIONAL labels, completion gate, spec summary, and 05-validation.md links to root AGENTS.md Service Routing Table
approval
../../patterns/, AGENTS.md paths use../../../AGENTS.md)The GAI Coding Policy And Copyright Annotation Best Practices
I certified that