Skip to content

docs: split architecture into owner documents and tighten agent guidance - #9863

Merged
joshistoast merged 7 commits into
mainfrom
chore/update-agents-md
Oct 15, 2026
Merged

joshistoast merged 7 commits into
mainfrom
chore/update-agents-md

Conversation

@joshistoast

@joshistoast joshistoast commented Oct 15, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Agent guidance was long, partly stale, and routed every ownership change through a 56 KB architecture doc. This PR:

  • Moves per-feature behavior specs out of invokeai/frontend/webv2/ARCHITECTURE.md (56 KB → 18 KB) into owner READMEs, listed in a new "Owner documents" table, and adds short AGENTS.md pointers next to the Canvas, projects, and extensions docs.
  • Fixes stale references: removed workbench/backend and migrated ownership rows, deleted test files cited by the Canvas doc, and paths with no stated root.
  • Adds invokeai/frontend/webv2/performance/README.md: what each performance gate checks, causes and fixes per failure message, byte-budget rules, and remediation tickets.
  • Tightens all AGENTS.md files and owner specs into shorter sentences without dropping conditions; adds rules for delegation (every file edit goes through an implementation subagent), stable review candidates, shared-resource coordination, and repo guidance overriding external skill defaults.
  • Adds pnpm dev:mock (Vite against the in-repo mock backend on a free port), a shared dragWithMouse test helper for dnd-kit droppables enabled after drag start, and performance gate failures that name the counted specifier, the fix, and the guide.
  • Replaces pnpm -C <package> from the root with running pnpm in the package directory (Corepack resolves pnpm per directory) in docs and two Makefile targets.

QA Instructions

From invokeai/frontend/webv2:

  • pnpm lint: passed.
  • pnpm test:browser src/features/gallery/ui/GalleryBoardsPanel.browser.test.tsx: 25/25 with the shared drag helper; a single-jump variant fails 3 drag tests.
  • pnpm check:release: test:browser had 2 failures under load (WorkbenchHotkeyRuntime.modal, WorkflowFieldInput), both untouched by this PR; each passed 81/81 twice when rerun alone. The remaining gates then ran and passed: test:fixtures, test:performance:architecture, test:project-files:browser, test:accessibility:browser.
  • Gate messages: with the @platform/ui importer budget temporarily lowered, the build gate reports platformUiBarrel has 160 direct importers of @platform/ui (budget 150), the subpath remedy, and Causes and fixes: invokeai/frontend/webv2/performance/README.md. A forced editor-runtime hit reports the same guide line.
  • pnpm dev:mock --port 5373 --strictPort: page and proxied /api return 200; SIGTERM exits 143 and SIGKILL of Vite exits 137, releasing both ports.
  • Docs: oxfmt --check clean; every relative link resolves; every path resolves from each doc's stated root.

The later doc-only commits ran formatting and link checks, not application suites.

Review

Resolved findings: wrong default Vite port (5174), editor-runtime failures missing the guide pointer, a Canvas doc sentence overstating the dependency rule, remaining pnpm -C docs, dev:mock reporting exit 0 on signal death, and wording that changed meaning while tightening (authentication dropped from "auth", "modify" widened to "touch", lock-order example read as the full rule, requirements read as facts). The extensions README no longer claims header menus render menu contributions; nothing reads registered menus yet.

Checklist

  • The PR has a short but descriptive title, suitable for a changelog
  • Meaningful regression coverage added / updated where needed; obsolete tests/code removed
  • Persisted-state and API changes include required migrations / compatibility validation
  • Relevant performance/efficiency opportunities considered; material claims have evidence
  • Material review findings resolved and relevant checks rerun
  • Documentation added / updated (if applicable)
  • Updated What's New copy (if doing a release after this PR)

View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith-bot with what you need.

…guidance

Split ARCHITECTURE.md into owner READMEs, fix stale ownership and path references, and add delegation, review, and performance-gate guidance.
Add `pnpm dev:mock`, a shared stepped-drag test helper, and performance gate failures that name the fix.
Run pnpm from package directories instead of `pnpm -C` from the root.
Compress AGENTS.md files, architecture docs, and owner READMEs into shorter sentences without dropping conditions.
Correct the extensions README: nothing renders registered menu contributions yet.
The main agent plans, briefs, integrates, and validates; implementers make all repository edits so the main conversation keeps its context.
Agents without subagent support edit locally.
@github-actions github-actions Bot added CI-CD Continuous integration / Continuous delivery python PRs that change python files Root backend PRs that change backend files frontend-deps PRs that change frontend dependencies frontend PRs that change frontend files python-tests PRs that change python tests docs PRs that change docs labels Oct 15, 2026
@joshistoast
joshistoast enabled auto-merge (squash) October 15, 2026 21:14

@JPPhoto JPPhoto left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change:

  • invokeai/frontend/webv2/src/workbench/canvas-engine/ARCHITECTURE.md:209: The documented @vitest/browser-playwright version is 4.1.9; package and lockfile use 5.0.0. This mismatch also exists in the base. Update the version separately.

The pinned version lives in package.json; the doc no longer duplicates it.
@joshistoast
joshistoast merged commit dee0166 into main Oct 15, 2026
17 checks passed
@joshistoast
joshistoast deleted the chore/update-agents-md branch October 15, 2026 21:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

backend PRs that change backend files CI-CD Continuous integration / Continuous delivery docs PRs that change docs frontend PRs that change frontend files frontend-deps PRs that change frontend dependencies python PRs that change python files python-tests PRs that change python tests Root

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants