Skip to content

docs: validate Epic 184 story #711

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rafaelscosta merged 1 commit into from
May 8, 2026
Merged

docs: validate Epic 184 story #711

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions docs/stories/epic-184-kimi-provider/EPIC-184-KIMI-K2-5-PROVIDER.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -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

Expand All @@ -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
Expand Down
49 changes: 44 additions & 5 deletions docs/stories/epic-184-kimi-provider/STORY-184.1-OPENAI-COMPATIBLE-KIMI-PROVIDER.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -21,8 +21,8 @@
## Status

- [x] Draft
- [ ] PO validated
- [ ] Ready for implementation
- [x] PO validated
- [x] Ready for implementation
- [ ] Ready for Review
- [ ] Done

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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.
Expand All @@ -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

Expand All @@ -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. |
Loading