From 5e9039382bec990325b1875704dec7659168d456 Mon Sep 17 00:00:00 2001 From: rafaelscosta Date: Fri, 8 May 2026 17:29:15 -0300 Subject: [PATCH] docs: validate epic 184 story [Story 184.1] --- .../EPIC-184-KIMI-K2-5-PROVIDER.md | 11 ++++- ...Y-184.1-OPENAI-COMPATIBLE-KIMI-PROVIDER.md | 49 +++++++++++++++++-- 2 files changed, 53 insertions(+), 7 deletions(-) diff --git a/docs/stories/epic-184-kimi-provider/EPIC-184-KIMI-K2-5-PROVIDER.md b/docs/stories/epic-184-kimi-provider/EPIC-184-KIMI-K2-5-PROVIDER.md index 28ce0cafeb..f33977191d 100644 --- a/docs/stories/epic-184-kimi-provider/EPIC-184-KIMI-K2-5-PROVIDER.md +++ b/docs/stories/epic-184-kimi-provider/EPIC-184-KIMI-K2-5-PROVIDER.md @@ -5,7 +5,7 @@ | Campo | Valor | |-------|-------| | Epic ID | 184 | -| Status | Draft | +| Status | Ready | | Source Issue | #184 | | Issue URL | https://github.com/SynkraAI/aiox-core/issues/184 | | Repository | SynkraAI/aiox-core | @@ -45,7 +45,7 @@ Adicionar suporte nativo e backward-compatible para Kimi K2.5 da Moonshot AI com | Story | Título | Status | Prioridade | Ordem | |-------|--------|--------|------------|-------| -| 184.1 | OpenAI-Compatible Kimi Provider Contract | Draft | P4 | 1 | +| 184.1 | OpenAI-Compatible Kimi Provider Contract | Ready | P4 | 1 | ## Ordem de Execução @@ -70,6 +70,13 @@ Adicionar suporte nativo e backward-compatible para Kimi K2.5 da Moonshot AI com - `npm run typecheck` - `npm run validate:manifest`, se novos arquivos entrarem no pacote instalável. +## PO Validation + +- Story 184.1 validada em 2026-05-08 contra `origin/main` após merge do PR #710. +- Nenhuma story anterior existe na Epic 184, então não há divergência cross-story. +- Ajustes adicionados à story: export do provider em `index.js`, atualização de README/template `.aiox-ai-config.yaml`, fallback configurável no `subagent-dispatcher` e neutralização do JSDoc CLI-only em `AIProvider`. +- Resultado: Ready para implementação, mantendo #184 aberto até existir evidência runtime. + ## Referências - Issue #184: https://github.com/SynkraAI/aiox-core/issues/184 diff --git a/docs/stories/epic-184-kimi-provider/STORY-184.1-OPENAI-COMPATIBLE-KIMI-PROVIDER.md b/docs/stories/epic-184-kimi-provider/STORY-184.1-OPENAI-COMPATIBLE-KIMI-PROVIDER.md index 38c252ea13..4e1c6415af 100644 --- a/docs/stories/epic-184-kimi-provider/STORY-184.1-OPENAI-COMPATIBLE-KIMI-PROVIDER.md +++ b/docs/stories/epic-184-kimi-provider/STORY-184.1-OPENAI-COMPATIBLE-KIMI-PROVIDER.md @@ -6,7 +6,7 @@ |-------|-------| | Story ID | 184.1 | | Epic | [184 - Kimi K2.5 Provider Support](./EPIC-184-KIMI-K2-5-PROVIDER.md) | -| Status | Draft | +| Status | Ready | | Executor | @dev | | Quality Gate | @architect | | quality_gate_tools | npm test focused, npm run lint, npm run typecheck, npm run validate:manifest | @@ -21,8 +21,8 @@ ## Status - [x] Draft -- [ ] PO validated -- [ ] Ready for implementation +- [x] PO validated +- [x] Ready for implementation - [ ] Ready for Review - [ ] Done @@ -77,6 +77,8 @@ The correct implementation path is a reusable `OpenAICompatibleProvider` plus a - [ ] AC8: Documentation shows `.aiox-ai-config.yaml` examples for Moonshot/Kimi and OpenRouter-style overrides without committing secrets. - [ ] AC9: Existing Claude/Gemini provider tests continue to pass unchanged in behavior. - [ ] AC10: The story does not merge or depend on the stale Kimi IDE sync worktree; IDE sync can become a separate future story if still desired. +- [ ] AC11: `.aiox-core/infrastructure/integrations/ai-providers/index.js`, provider README and `.aiox-core/product/templates/aiox-ai-config.yaml` expose the new provider without changing current Claude/Gemini defaults. +- [ ] AC12: `subagent-dispatcher.js` continues to work when the selected provider is `kimi` or `openai-compatible`, including fallback selection from configuration rather than hardcoding only Claude/Gemini. ## CodeRabbit Integration @@ -112,6 +114,8 @@ The correct implementation path is a reusable `OpenAICompatibleProvider` plus a - [ ] T5: Update docs with Kimi/Moonshot and OpenRouter configuration examples. - [ ] T6: Update manifest/entity registry only if required by existing packaging gates. - [ ] T7: Run focused tests, lint, typecheck and manifest validation. +- [ ] T8: Export `OpenAICompatibleProvider` from the provider module index and factory exports. +- [ ] T9: Update `subagent-dispatcher.js` fallback logic so configured non-CLI providers do not fall back through a hardcoded Claude/Gemini toggle. ## Dev Notes @@ -121,6 +125,10 @@ The correct implementation path is a reusable `OpenAICompatibleProvider` plus a - Treat `baseURL` and `baseUrl` as equivalent input names for compatibility with common OpenAI-style config. - Preserve current default provider behavior: `primary: claude`, `fallback: gemini`. - The stale `aiox-core-kimi` branch/worktree is scoped to IDE sync and should not be replayed into this story without a separate decision. +- `ai-provider.js` currently describes the base class as CLI-focused; implementation should update wording/contracts only as needed so HTTP providers are first-class while preserving the existing `AIResponse` shape. +- `ai-provider-factory.js` currently merges only `claude` and `gemini` config keys; implementation must merge configured OpenAI-compatible provider keys without dropping unknown provider configs. +- `getAvailableProviders()` and `getProvidersStatus()` currently hardcode `claude` and `gemini`; implementation should derive the provider set from defaults plus configured providers and aliases. +- Existing factory tests currently do not `await` async provider status functions; new or updated tests should make async assertions deterministic. ## Testing @@ -138,16 +146,45 @@ If the provider test lands under a different path, update this section and the F ## Dependencies -- **Blocked by:** PO/architect validation of this draft. +- **Blocked by:** None after PO validation on 2026-05-08. - **Blocks:** issue #184 closure. - **Related:** issue #137; existing LLM routing docs; Kimi IDE sync branch is adjacent but not in scope. ## Definition of Ready -- [ ] PO validation completed with no unresolved blocker. +- [x] PO validation completed with no unresolved blocker. - [x] Target provider surfaces confirmed against current code reality. - [x] Acceptance criteria are testable without live API calls. +## PO Validation Report + +### Phase 0: Epic Context + +- Epic context loaded from `docs/stories/epic-184-kimi-provider/EPIC-184-KIMI-K2-5-PROVIDER.md`. +- Stories analyzed: 0 Done, 0 InReview, 1 Draft/Ready. +- Findings from prior stories: none. This is the first and only story in Epic 184. +- Filesystem conflicts: none. `OpenAICompatibleProvider` does not exist yet. +- Dependency status: all met after publishing the Epic/Story plan in PR #710. + +### D10 Incremental Analysis + +- No previous completed story exists in Epic 184, so there is no executor, schema, endpoint or IDS divergence from earlier work. +- Adjacent stale `aiox-core-kimi` branch/worktree remains out of scope because it targets IDE sync rather than runtime LLM provider support. + +### Code Reality Check + +- `ai-provider-factory.js` still registers only `claude` and `gemini`, and `getAvailableProviders()`/`getProvidersStatus()` are hardcoded to those providers. +- `index.js` exports only `AIProvider`, `ClaudeProvider`, `GeminiProvider` and factory helpers, so the new provider must be exported there as part of the implementation. +- `subagent-dispatcher.js` obtains providers through the factory but fallback logic currently toggles between Claude and Gemini; this must be generalized for Kimi/OpenAI-compatible providers. +- `.aiox-core/product/templates/aiox-ai-config.yaml` and provider README currently document only Claude/Gemini configuration. +- Existing `ai-provider-factory.test.js` covers the current factory surface but should be updated with deterministic async assertions for status/availability checks. + +### Verdict + +- PASS for implementation readiness. +- No blocker remains for `@dev` to implement Story 184.1. +- Required adjustment: keep #184 open until runtime implementation, tests and validation are merged. + ## Definition of Done - [ ] All ACs complete. @@ -166,6 +203,7 @@ If the provider test lands under a different path, update this section and the F - Identified stale `aiox-core-kimi` branch/worktree as IDE sync scope, not provider LLM scope. - Confirmed current provider factory registers `claude` and `gemini` only. - Verified current Kimi API docs: OpenAI-compatible base URL is `https://api.moonshot.ai/v1`, and the chat completions endpoint relative to that base URL is `/chat/completions`. +- PO validation completed on 2026-05-08 after PR #710 was merged to `main`; #184 was reopened because planning alone does not close implementation. ### Agent Model Used @@ -187,3 +225,4 @@ If the provider test lands under a different path, update this section and the F | Data | Agente | Mudança | |------|--------|---------| | 2026-05-08 | @sm / Codex | Epic/story draft criados a partir do issue #184, leitura do provider factory atual e documentação oficial Kimi API. | +| 2026-05-08 | @po / Codex | Story validada contra `origin/main`, ajustes técnicos adicionados e status movido para Ready. |