Conversation
Greptile SummaryThis PR adds a design-only spec for inline setup guidance in the Control UI, covering Confidence Score: 4/5Design-only doc, safe to merge — only P2 design clarity notes flagged. No implementation changes; only a spec document is added. Two P2 concerns exist — docs/superpowers/specs/2026-04-25-control-ui-setup-guidance-design.md — Prompt To Fix All With AIThis is a comment left during a code review.
Path: docs/superpowers/specs/2026-04-25-control-ui-setup-guidance-design.md
Line: 99-107
Comment:
**`docsPath` type ambiguity**
The field name `docsPath` and its description ("docs path or docs link if present") conflate two distinct shapes: a Mintlify root-relative path (e.g. `/channels/discord`) and a fully-qualified URL. The rendering code will need to know which to expect — root-relative paths require URL construction at the gateway/UI boundary, while full URLs do not. Per `docs/AGENTS.md`, internal doc links are root-relative with no `.md` suffix. Consider splitting the field (e.g. `docsUrl?: string`) or tightening the prose to specify exactly what format is expected.
How can I resolve this? If you propose a fix, please make it concise.
---
This is a comment left during a code review.
Path: docs/superpowers/specs/2026-04-25-control-ui-setup-guidance-design.md
Line: 110-130
Comment:
**Shared type risks silent drift between skills and channels**
The spec plants the same `SetupGuidance` shape in two separate files — `src/agents/skills-status.ts` and `src/channels/plugins/setup-wizard-types.ts`. If both keep independent copies, the two will silently diverge when one side adds a field (e.g. `priority` or a locale hint). Consider declaring `SetupGuidance` once in a shared types module (e.g. `src/shared/setup-guidance-types.ts` or inside a UI package) and importing it from both sites, so there is a single source of truth for the contract.
How can I resolve this? If you propose a fix, please make it concise.Reviews (1): Last reviewed commit: "docs: add control ui setup guidance desi..." | Re-trigger Greptile |
| copyText?: string; | ||
| details?: string[]; | ||
| docsPath?: string; | ||
| }; | ||
| ``` | ||
|
|
||
| Rules: | ||
|
|
||
| - `summary` is always present when setup guidance exists. |
There was a problem hiding this comment.
docsPath type ambiguity
The field name docsPath and its description ("docs path or docs link if present") conflate two distinct shapes: a Mintlify root-relative path (e.g. /channels/discord) and a fully-qualified URL. The rendering code will need to know which to expect — root-relative paths require URL construction at the gateway/UI boundary, while full URLs do not. Per docs/AGENTS.md, internal doc links are root-relative with no .md suffix. Consider splitting the field (e.g. docsUrl?: string) or tightening the prose to specify exactly what format is expected.
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/superpowers/specs/2026-04-25-control-ui-setup-guidance-design.md
Line: 99-107
Comment:
**`docsPath` type ambiguity**
The field name `docsPath` and its description ("docs path or docs link if present") conflate two distinct shapes: a Mintlify root-relative path (e.g. `/channels/discord`) and a fully-qualified URL. The rendering code will need to know which to expect — root-relative paths require URL construction at the gateway/UI boundary, while full URLs do not. Per `docs/AGENTS.md`, internal doc links are root-relative with no `.md` suffix. Consider splitting the field (e.g. `docsUrl?: string`) or tightening the prose to specify exactly what format is expected.
How can I resolve this? If you propose a fix, please make it concise.| - `docsPath` is fallback/supporting guidance, not the primary copied action. | ||
|
|
||
| ## Skills Source Of Truth | ||
|
|
||
| Add optional `setupGuidance` to `SkillStatusEntry` in `src/agents/skills-status.ts`. | ||
|
|
||
| Build it centrally from existing skill status metadata: | ||
|
|
||
| - `install` | ||
| - `missing` | ||
| - `primaryEnv` | ||
| - config checks | ||
|
|
||
| Priority for skill `copyText`: | ||
|
|
||
| 1. installer command/snippet derived from the preferred install option | ||
| 2. env snippet derived from `primaryEnv` | ||
| 3. config-path hint when no better command/snippet exists | ||
|
|
||
| The UI must not derive commands from labels like `Install ...`. The status layer should provide the explicit copy payload. | ||
|
|
There was a problem hiding this comment.
The spec plants the same SetupGuidance shape in two separate files — src/agents/skills-status.ts and src/channels/plugins/setup-wizard-types.ts. If both keep independent copies, the two will silently diverge when one side adds a field (e.g. priority or a locale hint). Consider declaring SetupGuidance once in a shared types module (e.g. src/shared/setup-guidance-types.ts or inside a UI package) and importing it from both sites, so there is a single source of truth for the contract.
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/superpowers/specs/2026-04-25-control-ui-setup-guidance-design.md
Line: 110-130
Comment:
**Shared type risks silent drift between skills and channels**
The spec plants the same `SetupGuidance` shape in two separate files — `src/agents/skills-status.ts` and `src/channels/plugins/setup-wizard-types.ts`. If both keep independent copies, the two will silently diverge when one side adds a field (e.g. `priority` or a locale hint). Consider declaring `SetupGuidance` once in a shared types module (e.g. `src/shared/setup-guidance-types.ts` or inside a UI package) and importing it from both sites, so there is a single source of truth for the contract.
How can I resolve this? If you propose a fix, please make it concise.* docs: add control ui setup guidance design * chore: keep superpowers plans local
* docs: add control ui setup guidance design * chore: keep superpowers plans local
* docs: add control ui setup guidance design * chore: keep superpowers plans local
* docs: add control ui setup guidance design * chore: keep superpowers plans local
Summary
Notes