microsoft / microsoft/agent-governance-toolkit

AGT Studio: package + CI scaffold + CODEOWNERS (Epic 1a, issue 5/32)

Open
#3,898 1 comment 0 reactions 0 assignees View on GitHub
agent-governance architecture ci/cd enhancement
Dominant language
Python
Stars
6.3k
Forks
1.1k
Avg merge
5d 11h
Merged PRs (30d)
142

Description

Tracker: #2729
Epic: 1a - Studio package, ownership, and CI scaffold (issue 5/32)
Milestone: AGT Studio

Re-files #2789, which was closed as **not planned** because it was filed before maintainer plan review, not because the scaffold was implemented. This issue replaces that draft with scope aligned to the current repository layout, CI architecture, and implementation-quality rules.

### Package

New package / cross-cutting - new top-level `agent-governance-studio/` package plus narrowly scoped updates to existing repository CI, dependency automation, and ownership configuration.

### Problem Statement

AGT Studio has a binding architecture and execution sequence in ADR 0028 and #2729, but it does not yet have a package boundary or build surface. The next sidecar, SPA, and launcher issues need a canonical location with stable Python/npm identities, reproducible toolchains, tests that actually execute, path-filtered CI, and explicit ownership.

Without this scaffold, later issues would each make overlapping package and workflow decisions, increasing merge conflicts and the risk of inconsistent dependency, licensing, and supply-chain controls.

### How does this feature impact your work and what are you trying to achieve?

This is the first Studio implementation issue and the foundation for Epics 1b-1d and every later Studio panel. It creates a buildable, testable package without implementing the sidecar, CLI launchers, transport abstraction, generated client, or product UI ahead of their dedicated issues.

### Timeline

Next in the #2729 execution order after the Epic 0 Engine API work. No calendar deadline specified.

### Proposed Solution

#### 1. Establish the canonical package boundary

Create the top-level `agent-governance-studio/` directory using the names locked by #2729:

| Surface | Required name |
|---|---|
| Repository directory | `agent-governance-studio/` |
| Python distribution | `agent-governance-studio` |
| Python import package | `agent_governance_studio` |
| npm package | `@microsoft/agent-governance-studio` |

The Python distribution uses a `src/agent_governance_studio/` layout and the repository's current lockstep version. Package metadata must identify the package as Public Preview, Microsoft-authored, and MIT-licensed. Add only the minimum real package surface needed for import/build verification; do not register `agt ui` or `agt serve` until their implementation issues land.

The frontend lives under `agent-governance-studio/web/` and uses the locked stack: React 18, TypeScript, Vite, TanStack Query, and Tailwind. Provide the minimum real application entry and smoke coverage needed to prove the toolchain works. Do not add navigation, Engine API calls, transport abstractions, policy screens, or placeholder production commands.

Do not add empty `server/`, `cli/`, or feature directories solely to reserve names. Later issues should create those modules when they contain working implementations.

#### 2. Add reproducible manifests and developer commands

Add the package manifests and configuration required to support these repository-root workflows:

```text
python -m build agent-governance-studio
python -m pytest agent-governance-studio/tests -q
ruff check agent-governance-studio/src agent-governance-studio/tests --select E,F,W --ignore E501

npm ci --prefix agent-governance-studio/web
npm run lint --prefix agent-governance-studio/web
npm test --prefix agent-governance-studio/web
npm run build --prefix agent-governance-studio/web
```

The exact scripts may delegate to package-local configuration, but all four frontend commands must be present and non-no-op. Commit `package-lock.json`; use exact npm versions without `^` or `~`. Any new dependency must satisfy the repository's 7-day stability and supply-chain checks. Do not add a Python runtime dependency until production code requires it.

Include package-local ignore rules and a concise `README.md` that identifies this as the canonical AGT Studio package, links to #2729 and `docs/adr/0028-agt-studio-unified-ui.md`, documents local validation commands, and states that functional sidecar/SPA/launcher work is intentionally deferred.

#### 3. Integrate with existing path-filtered CI

Extend `.github/workflows/ci.yml`; do not introduce a parallel CI architecture. Studio-only changes must select Studio validation, and unrelated package changes must not.

CI must:

- install the Python package/build tooling using existing pinned repository dependency surfaces;
- run Python lint, tests, and wheel/sdist build;
- use the checked-in npm lockfile with `npm ci` and run frontend lint, tests, and production build;
- fail if required tests are missing, skipped as a whole, or configured as no-op scripts;
- run for changes under `agent-governance-studio/**` and for relevant Studio CI configuration changes;
- preserve SHA-pinned actions and top-level `permissions: contents: read`;
- keep the Studio job(s) independently gated so existing Python and TypeScript package matrices are not forced to run for unrelated changes.

A dedicated Studio job inside the existing workflow is acceptable because the top-level package contains both Python and npm build surfaces; a new standalone workflow is not required.

#### 4. Add dependency automation and explicit ownership

Add `/agent-governance-studio/web` to `.github/dependabot.yml` using the repository's weekly npm cadence, 7-day cooldown, dependency labels, and commit-message conventions.

Add an explicit `/agent-governance-studio/` entry to `.github/CODEOWNERS` using the current repository owners `@MohammadHaroonAbuomar @liamcrumm`. The explicit entry documents ownership even though the current global rule already covers the directory.

#### 5. Required repository-quality details

- Add MIT headers to every new source file.
- Keep all text files UTF-8 with trailing newlines.
- Use type-safe frontend configuration; do not bypass checks with `any` casts.
- Ensure the Python wheel and sdist contain the intended Python package files and no frontend build output or dependency directories unless explicitly configured and tested.
- Do not modify release/publishing pipelines in this issue. Publishing remains through the repository's ESRP process once Studio has a shippable surface.
- Keep `.github/` changes limited to the existing CI workflow, Dependabot configuration, and CODEOWNERS entries required by this scaffold.

### Deliverables

| Path | Deliverable |
|---|---|
| `agent-governance-studio/pyproject.toml` | Final Python distribution/import identity, build metadata, and test/lint configuration as needed. |
| `agent-governance-studio/src/agent_governance_studio/` | Minimal importable package with no placeholder command implementations. |
| `agent-governance-studio/tests/` | Real package/import/metadata smoke coverage. |
| `agent-governance-studio/web/` | Locked React 18 + TypeScript + Vite + TanStack Query + Tailwind toolchain, exact dependency versions, lockfile, minimal entry, and smoke test. |
| `agent-governance-studio/README.md` | Scope, architecture links, and reproducible local commands. |
| `.github/workflows/ci.yml` | Path-filtered Studio lint/test/build gate integrated into existing CI. |
| `.github/dependabot.yml` | Weekly npm updates for the Studio web package with the existing cooldown policy. |
| `.github/CODEOWNERS` | Explicit Studio ownership using current repository maintainers. |

### Acceptance criteria

- [ ] The directory and package identities exactly match #2729's locked decision: `agent-governance-studio`, `agent_governance_studio`, and `@microsoft/agent-governance-studio`.
- [ ] The Python package builds as both wheel and sdist, installs in a clean environment, and imports successfully without registering unimplemented `agt` commands.
- [ ] The frontend uses React 18, TypeScript, Vite, TanStack Query, and Tailwind with exact dependency versions and a committed `package-lock.json`.
- [ ] Frontend lint, tests, and production build are real, non-no-op commands and pass from a clean `npm ci` install.
- [ ] At least one Python test and one frontend test execute so CI cannot report success solely because no tests were collected.
- [ ] `.github/workflows/ci.yml` selects Studio validation for `agent-governance-studio/**`, runs both language surfaces, and does not trigger unrelated package matrices for a Studio-only change.
- [ ] `.github/dependabot.yml` includes the Studio npm directory with the repository's weekly schedule and 7-day cooldown.
- [ ] `.github/CODEOWNERS` contains an explicit Studio path entry with `@MohammadHaroonAbuomar @liamcrumm`.
- [ ] New source files have MIT headers; manifests follow repository metadata and version-locking rules; package descriptions use the Public Preview prefix.
- [ ] The README links to #2729 and ADR 0028, documents local commands, and accurately states that sidecar, launcher, transport, generated-client, and product UI behavior are out of scope.
- [ ] No empty feature directories, placeholder CLI/server methods, mock production integrations, new runtime write path, or publishing workflow changes are included.
- [ ] Existing workflow security remains intact: actions are SHA-pinned, permissions remain least-privilege, and supply-chain checks pass for all new manifests and lockfiles.
- [ ] This issue is linked from #2729 with the AGT Studio milestone; the umbrella row is updated to `Filed` after creation and to `Closed` when all acceptance criteria are complete.

### Alternatives Considered

- **Keep Studio under an existing Python or TypeScript package:** rejected by #2729's locked package-layout decision and would blur ownership between the UI product and existing SDK/runtime packages.
- **Create only empty directories and placeholder commands:** rejected because it would not prove packaging or CI and conflicts with the repository's no-stub implementation rule.
- **Build the sidecar or SPA shell in the scaffold PR:** rejected to preserve the sequential issue boundaries; those behaviors belong to Epics 1b and 1c.
- **Add a new standalone workflow:** unnecessary; the existing path-filtered CI is the repository's canonical architecture and can host a dedicated Studio gate.

### Priority

Important - this issue blocks the remaining AGT Studio implementation sequence.

Contributor guide

Open the contributing guide

Research direction

Start by reading ADR 0028, #2729, the existing path-filtered .github/workflows/ci.yml, .github/dependabot.yml, and .github/CODEOWNERS. Create the package under agent-governance-studio/ and validate with the listed Python build/test/lint commands plus npm ci, lint, test, and build; done means the acceptance criteria pass without adding deferred Studio functionality.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, react, tailwindcss, typescript, vite
Domain
build-system, ci-cd, developer-experience, frontend, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.