Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
The diff you're trying to view is too large. We only load the first 3000 changed files.
10 changes: 5 additions & 5 deletions .agents/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ This directory follows the [agentskills.io](https://agentskills.io) specificatio
│ │ ├── SKILL.md
│ │ └── scripts/
│ │ ├── diff-scan.sh
│ │ └── tests/
│ │ └── development/testing/tests/
│ │ └── run-tests.sh
│ ├── debug-issue/
│ │ └── SKILL.md
Expand All @@ -52,20 +52,20 @@ This directory follows the [agentskills.io](https://agentskills.io) specificatio
```

Shared engineering guidance is in [docs](../docs/README.md). Catalog workflows
remain in [their package](../packages/kumo-ui-catalog/.agents/README.md).
remain in [their package](../packages/ui/kumo-ui-catalog/.agents/README.md).

## Skills (agentskills.io spec)

| Skill | Purpose |
|-------|---------|
| `build-ui` | Orchestrate UI ticket work from GitHub issue through implementation, validation, and PR creation |
| `code-ui` | Scaffold and implement UI features following Kumo conventions (ui/src/) |
| `review-ui` | Review code against UI standards (ui/src/) |
| `code-ui` | Scaffold and implement UI features following Kumo conventions (apps/studio/ui/src/) |
| `review-ui` | Review code against UI standards (apps/studio/ui/src/) |
| `debug-issue` | Investigate GitHub issues with source, logs, analysis, and optional consultation |
| `preflight` | Validate local prerequisites for the requested workflow |
| `check-logs` | Read supplied logs or collect logs from a selected Kubernetes workload |
| `investigate-training-stage` | Investigate stuck or slow Temporal training and prediction stages |
| `review-ml` | Review service ML adapters and the shared runtime in packages/kumo-core against ML standards |
| `review-ml` | Review service ML adapters and the shared runtime in packages/runtime/kumo-core against ML standards |

## Additional catalog skills

Expand Down
2 changes: 1 addition & 1 deletion .agents/hooks/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ When Claude Code writes or edits a Python file, this hook:
```
✓ isort: imports sorted
⚠ flake8 violations:
kumo/data/session_utils.py:16:1: F401 'kumo.data.backend_utils' imported but unused
apps/studio/kumo/data/session_utils.py:16:1: F401 'kumo.data.backend_utils' imported but unused
```

### Requirements
Expand Down
2 changes: 1 addition & 1 deletion .agents/hooks/validate_agent_docs.py
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ def get_project_root():
"""Get the project root directory."""
if "CLAUDE_PROJECT_DIR" in os.environ:
return Path(os.environ["CLAUDE_PROJECT_DIR"])
return Path(__file__).parent.parent.parent
return Path(__file__).resolve().parents[2]


def get_skill_info(skill_file: Path) -> dict:
Expand Down
2 changes: 1 addition & 1 deletion .agents/scripts/sync-mcp.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ def get_project_root():
if "CLAUDE_PROJECT_DIR" in os.environ:
return Path(os.environ["CLAUDE_PROJECT_DIR"])
# Walk up from script location
script_dir = Path(__file__).parent
script_dir = Path(__file__).resolve().parents[0]
return script_dir.parent.parent


Expand Down
24 changes: 12 additions & 12 deletions .agents/skills/build-ui/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: Orchestrate Kumo UI ticket work from GitHub issue analysis through

# Build UI

Use this skill when the user wants to implement a UI GitHub issue end-to-end, continue work from an existing UI PR, or run a ticket-to-PR workflow for changes in `ui/src/`.
Use this skill when the user wants to implement a UI GitHub issue end-to-end, continue work from an existing UI PR, or run a ticket-to-PR workflow for changes in `apps/studio/ui/src/`.

This skill is the orchestrator.

Expand Down Expand Up @@ -102,15 +102,15 @@ Supporting references:
- `references/handoff-examples.md`
- `references/output-contracts.md`
- `references/screenshot-operator-guide.md`
- `ui/src/screenshot/catalog.json`
- `apps/studio/ui/src/screenshot/catalog.json`
- `references/pr-workflow.md`
- `references/run-state-template.json`
- `references/workflow-test-scenarios.md`

Screenshot quality bar:

- screenshot success means the changed UI was visually verified, not merely that a route loaded
- for known surfaces, prefer `ui/src/screenshot/catalog.json` recipes over freeform plans
- for known surfaces, prefer `apps/studio/ui/src/screenshot/catalog.json` recipes over freeform plans
- every user-visible requirement that should be proven in the screenshot should have a matching assertion
- catalog recipes should declare structured `visualCoverage` items with stable IDs, and setup/actions/assertions should use `covers` with those IDs so coverage intent is tied to concrete selectors
- reusable screenshot fixtures should be used for common deterministic states instead of repeating brittle live-data interactions
Expand Down Expand Up @@ -550,8 +550,8 @@ Only after Checkpoint 1 approval:

```bash
git fetch origin
git branch --list "ui/{issue}-*"
git checkout -b ui/{issue}-{slug} origin/{base-branch}
git branch --list "apps/studio/ui/{issue}-*"
git checkout -b apps/studio/ui/{issue}-{slug} origin/{base-branch}
```

Rules:
Expand Down Expand Up @@ -744,7 +744,7 @@ Use `references/decision-tables.md` section "Auth And Runtime Config For Visual

Choose the capture path in this priority order:

1. **Local Playwright capture (default for known surfaces).** If a dev server is reachable and `ui/src/screenshot/catalog.json` has a recipe whose `patterns` match a changed file, capture with `ui/scripts/ci-screenshot.mjs` yourself — see "Local Playwright capture (interactive runs)" below. This is deterministic, reproducible, and produces the same evidence CI does. This applies in every interactive mode, not just headless CI.
1. **Local Playwright capture (default for known surfaces).** If a dev server is reachable and `apps/studio/ui/src/screenshot/catalog.json` has a recipe whose `patterns` match a changed file, capture with `apps/studio/ui/scripts/ci-screenshot.mjs` yourself — see "Local Playwright capture (interactive runs)" below. This is deterministic, reproducible, and produces the same evidence CI does. This applies in every interactive mode, not just headless CI.
2. **Browser MCP.** Use `mcp__chrome-devtools__*` tools only for freeform exploration of a surface with no matching recipe, or to investigate behavior a static screenshot cannot prove.
3. **Headless CI Playwright.** In headless/CI runs the workflow owns capture — see "CI Playwright Fallback".

Expand Down Expand Up @@ -774,12 +774,12 @@ If screenshots are captured:

In a local/interactive run (not headless CI), prefer this over browser MCP whenever a dev server is up and a catalog recipe matches the changed surface:

1. Find the matching recipe in `ui/src/screenshot/catalog.json` (match its `patterns` against the changed files; reuse its `canonicalRoutes`, `readySelector`, `setup`, and `visualCoverage`).
1. Find the matching recipe in `apps/studio/ui/src/screenshot/catalog.json` (match its `patterns` against the changed files; reuse its `canonicalRoutes`, `readySelector`, `setup`, and `visualCoverage`).
2. Write a plan to `/tmp/build-ui-screenshots/{issue-or-pr}/plan.json` — a `scenarios` array, each with `route`, deterministic `setup` steps, a `readySelector`, and `assertions` whose selectors target the exact changed element (not a page shell, tab list, or generic heading).
3. Capture against the local dev server:

```bash
node ui/scripts/ci-screenshot.mjs \
node apps/studio/ui/scripts/ci-screenshot.mjs \
--plan /tmp/build-ui-screenshots/{issue-or-pr}/plan.json \
--output /tmp/build-ui-screenshots/{issue-or-pr} \
--base-url http://localhost:3000 \
Expand All @@ -788,13 +788,13 @@ In a local/interactive run (not headless CI), prefer this over browser MCP whene

`--auth-disabled` injects the local sentinel token; the local dev backend accepts it and supplies the canonical project/group authorization context used by every deployment.
4. Inspect `results.json` and the saved PNG. If capture fails, debug the artifacts (`screenshot-debug.md`, the failed `*.html`/`*.png` under `failed/`) before changing the plan. Common gotchas: a first-run "Welcome to Kumo" modal intercepts clicks (dismiss via `[data-testid="cancel-icon"]`), and list pages may not auto-select a row (click `[data-testid="entity-name-0"]` to open the detail panel).
5. Publish to the PR with `ui/scripts/build-ui-publish-screenshots.mjs` in Phase 9 — same `images` branch and `## Screenshots` section as headless CI.
5. Publish to the PR with `apps/studio/ui/scripts/build-ui-publish-screenshots.mjs` in Phase 9 — same `images` branch and `## Screenshots` section as headless CI.

The "agent must not shell out to `ci-screenshot.mjs`" rule below applies only to headless CI mode, where the workflow runs it for you. In local runs, running it yourself is the intended path.

### CI Playwright Fallback

When `mcp__chrome-devtools__*` tools are unavailable but the environment variable `CI_SCREENSHOT_SCRIPT` is set (headless CI mode), the workflow runs Playwright on the agent's behalf. In that headless mode the agent must not shell out to `ui/scripts/ci-screenshot.mjs`.
When `mcp__chrome-devtools__*` tools are unavailable but the environment variable `CI_SCREENSHOT_SCRIPT` is set (headless CI mode), the workflow runs Playwright on the agent's behalf. In that headless mode the agent must not shell out to `apps/studio/ui/scripts/ci-screenshot.mjs`.

Instead, write a screenshot plan to `$BUILD_UI_ARTIFACT_DIR/screenshot-plan.json` with either:

Expand Down Expand Up @@ -886,7 +886,7 @@ If approved:
4. determine the release-notes label
5. detect breaking changes
6. create the PR from `.github/PULL_REQUEST_TEMPLATE.md`
7. if screenshots were captured, publish them with `ui/scripts/build-ui-publish-screenshots.mjs` after PR creation so local PRs use the same `images` branch and `## Screenshots` section as headless CI
7. if screenshots were captured, publish them with `apps/studio/ui/scripts/build-ui-publish-screenshots.mjs` after PR creation so local PRs use the same `images` branch and `## Screenshots` section as headless CI

Before creating the PR, run a final diff sanity pass:

Expand Down Expand Up @@ -938,7 +938,7 @@ Use the exact phase label from this table in `lastCompletedPhase`. Do not collap
Rules:

- reuse the existing work branch
- in `issue` mode, that is usually `ui/{issue}-*`
- in `issue` mode, that is usually `apps/studio/ui/{issue}-*`
- in `pr` mode with continuation, that is usually `{headRefName}`
- verify current branch state before skipping earlier stages
- resume only when the branch state clearly corresponds to the requested stage
Expand Down
12 changes: 6 additions & 6 deletions .agents/skills/build-ui/references/decision-tables.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,16 +33,16 @@ Fallback policy:
| Situation | Action |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Catalog present and installs healthy | Do nothing |
| Catalog source missing | Report an incomplete checkout; the source belongs at `packages/kumo-ui-catalog` |
| Catalog dependencies or build missing | From `ui/`, run `npm run install:catalog && npm install` when dependency setup is authorized; the catalog is an in-tree file dependency |
| Catalog source missing | Report an incomplete checkout; the source belongs at `packages/ui/kumo-ui-catalog` |
| Catalog dependencies or build missing | From `apps/studio/ui/`, run `npm run install:catalog && npm install` when dependency setup is authorized; the catalog is an in-tree file dependency |
| Lockfile reinstall explicitly intended | Run `npm ci` |
| Dependency path unclear | Stop and ask before mutating npm config |

## Catalog Gap Resolution

| Situation | Action |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Required variant/component missing from `kumo-ui-catalog` | Add it in `packages/kumo-ui-catalog` and update UI callers in the same repository |
| Required variant/component missing from `kumo-ui-catalog` | Add it in `packages/ui/kumo-ui-catalog` and update UI callers in the same repository |
| Catalog change exists in another PR but is not merged | Proceed with UI implementation assuming the variant will exist and add a blocking note in the PR description |
| User approves a temporary local workaround | Implement the workaround with a `TODO` tied to the catalog change and track removal in deferred scope |
| User wants to wait for the catalog change | Pause implementation and record the blocker in the handoff |
Expand All @@ -68,7 +68,7 @@ Rules:
| `AUTH_DISABLED` already true at runtime | Proceed (auth-disabled sentinel; no credentials needed) |
| `AUTH_DISABLED` false and `SCREENSHOT_AUTH_EMAIL`/`SCREENSHOT_AUTH_PASSWORD` in the env | Run the catalog-recipe capture (`npm run screenshots:build-ui`) — Direct Connect credentials take precedence and the browser password-login path is used, no `env.js` change |
| `AUTH_DISABLED` false and no credentials present | Ask the user to either provide credentials (env vars below), approve a local `env.js` bypass, or skip — do not silently skip |
| `AUTH_DISABLED` false and user approves local bypass change | Edit `ui/env.js`, then regenerate runtime config |
| `AUTH_DISABLED` false and user approves local bypass change | Edit `apps/studio/ui/env.js`, then regenerate runtime config |
| `AUTH_DISABLED` false and user declines | Skip visual testing |
| Runtime config still mismatched after update | Stop and report the exact mismatch |

Expand Down Expand Up @@ -117,7 +117,7 @@ Screenshot auth and planning decision points:
| Rebase conflicts occur | Stop and present conflicts |
| Release-notes label is obvious | Recommend it, confirm if needed |
| Label unclear | Ask explicitly before PR creation |
| Screenshots available and GitHub CLI can write to the repo | After PR creation, run `ui/scripts/build-ui-publish-screenshots.mjs` to publish primary images to the `images` branch, patch the PR body, and post the screenshot comment |
| Screenshots available and GitHub CLI can write to the repo | After PR creation, run `apps/studio/ui/scripts/build-ui-publish-screenshots.mjs` to publish primary images to the `images` branch, patch the PR body, and post the screenshot comment |
| Screenshots available but GitHub CLI cannot write to the repo | Skip upload and note in the PR that screenshots were verified locally |
| Screenshots available but browser tooling unavailable | Use the shared image-branch publisher; browser tooling is not required for screenshot upload |
| Screenshots captured via CI Playwright script | Screenshots are posted back to the PR or issue comment and uploaded as workflow artifacts. No browser-based GitHub upload needed. |
Expand Down Expand Up @@ -149,7 +149,7 @@ Do not use `pre-existing` without evidence.

## Shared Component Blast Radius

When a change touches shared UI under `src/components/@ui/`, `src/hooks/`, `src/stores/`, or other widely reused modules:
When a change touches shared UI under `src/components/@apps/studio/ui/`, `src/hooks/`, `src/stores/`, or other widely reused modules:

| Check | Action |
| ------------------------------------------------ | ----------------------------------------------------------------------- |
Expand Down
Loading