Skip to content

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

Open
joshistoast wants to merge 4 commits into
mainfrom
chore/update-agents-md
Open

joshistoast wants to merge 4 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
Commit attribution is a personal preference, not a repository rule.

This branch has not been deployed

No deployments
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.

1 participant