Independent design prototype repository

Status: Current | Last reviewed: 2026-10-06

Deloitte-US/agent-studio-design is a private, independently versioned repository embedded at studio/design as a Git submodule. The framework tracks its URL and a commit ID, not a second copy of its files. Designers can clone that repo alone and use its root npm install / npm run dev commands (port 3100).

The production source remains apps/ai-manager. The submodule contains the standalone export, including the same live UI components, mock APIs, shared package tarballs and designer coaching in its own root CLAUDE.md. No running production service or Docker build depends on checking it out.

The 2026-09-10 refresh resolves the initial Build draft / Open draft mock gap. All four types can build and open local sample drafts, labelled as simulated. Proposed responsibilities are not compiled and Performance records are not saved or executed. The designer repository's apps/ai-manager/docs/prototype-design-decisions.md records this contract and its limits. Eight prototype browser tests, the default 30-second browser test, typecheck, changed-source lint and two timing unit tests pass. ESLint excludes .next-prototype/ build output so npm run lint remains scoped to source after the standalone dev server has run. Full source lint at initialization reported four react-hooks/refs errors in the existing Pipeline/Workflow Yjs bridges; the designer README records those separately from the submodule workflow checks.

October 2026 branch consolidation

The local integration/vanguard-design-20261006 branch combines refreshed main, Lynn's work, Lisa's prototype updates and the older expanded-mock branch. The framework-sync baseline is already common ancestry. The production import favors designer layout and interaction choices, adapting real API contracts and retaining the legacy Performance page only by direct URL per the product decision. See the integration record for conflict resolutions, backend additions and preserved controls. This focused import does not export unrelated in-progress Vanguard work into the prototype. The local design main and framework submodule reference now point to 6c4bc3b; the consolidated history has not been pushed to the remote designer repository.

Designer autonomy and commit-time handoff

The prototype's root CLAUDE.md and AGENTS.md authorize the designer's requested visual and behavioral changes. Existing capabilities, required inputs and copied technical invariants are implementation references, not design vetoes. Agents may implement proposed interactions with local mocks without engineering signoff.

When preparing a commit, the agent updates apps/ai-manager/docs/design-change-log.md in the designer repository with the change, potential production impact, engineering follow-up and checks performed. Include the file with the commit. Unknown impact, missing backend work and failing checks are recorded, not used to block prototype work or commits. Detailed contracts can link to prototype-design-decisions.md; small visual changes need only a short note. No blocking pre-commit hook is installed.

Update the framework's prototype/designer-claude.md and the AGENTS.md text in prototype/scripts/export-repo.sh when changing policy, as well as the current standalone guides. This keeps future exports from restoring stricter instructions. The normal production validation and documentation requirements apply when importing the changes into apps/ai-manager.

Set up or update the checkout

From the framework root:

git submodule update --init studio/design
git -C studio/design switch main

The first command checks out the revision pinned by the framework, initially with a detached HEAD. Switch to a branch before making prototype changes. Access to the private prototype repo is required separately from framework access. A normal framework clone does not need --recurse-submodules.

To take the latest published designer work and update the framework's pointer:

git -C studio/design switch main
git -C studio/design pull --ff-only
git add studio/design

Review and commit that pointer in the framework as part of the relevant change. Ordinary git pull of the framework does not merge or publish designer work.

Two histories and two commits

main in the prototype repo carries designer changes. framework-sync is the last plain framework export; do not author design changes directly on it.

git -C studio/design status
git -C studio/design add <changed-files>
git -C studio/design commit -m "Describe the design change"
git -C studio/design push origin main
git add studio/design

Push the prototype commit before committing/pushing its new pointer in the framework. Do not commit the nested files as ordinary framework files. The framework records .gitmodules and the 160000 gitlink at studio/design.

Merge another designer branch

Fetch the nested repository's remote and inspect the intended branch before merging. Preserve local work in a checkpoint commit (with its change-log entry) or a named stash, then merge using Git's shared history:

git -C studio/design fetch origin --prune
git -C studio/design log --oneline main..origin/feature/lynn-wip
git -C studio/design merge --no-ff --no-commit origin/feature/lynn-wip

Reconcile overlapping design edits, record any capability/contract changes in the local log and run checks appropriate to the merged result before completing the merge commit. Record known failures rather than requiring a designer waiver. Do not replace the checkout with a fresh export or discard local work. A local merge does not push either repository or update production source automatically.

Bring core-app updates into the prototype

Commit/preserve designer work and pull its latest main first. Then run:

bash apps/ai-manager/prototype/scripts/sync-design-repo.sh
bash apps/ai-manager/prototype/scripts/sync-design-repo.sh --apply

The first command previews the current working-tree export delta. --apply commits it locally on framework-sync, then merges it into the prototype's main. This is a three-way Git merge against the previous export, preserving independent designer edits and surfacing genuine conflicts. It never mirrors the export directly over the designer checkout and never pushes either repo.

The helper requires a clean submodule on main, refreshes remote refs and refuses to proceed when newer designer commits or a prior sync merge remain unintegrated. It uses git, Node.js, tar and rsync. Temporary worktrees are removed after the operation. Resolve any merge conflicts inside studio/design and commit, or use git -C studio/design merge --abort to return to the prior main. The new framework-sync commit remains available to merge later.

After reviewing and testing:

git -C studio/design push origin main framework-sync
git add studio/design

Record the published pointer in the core change. The source snapshot includes uncommitted framework app changes, just like the ZIP exporter; review what belongs in a designer handoff before publishing it.

Bring designer changes into the real application

Review the prototype changes against its latest merged export baseline:

git -C studio/design diff framework-sync...main -- apps/ai-manager

Review shared UI, prototype mocks/fixtures and the handoff decision document separately, but retain all relevant parts. Port changes onto the current apps/ai-manager source with normal conflict/validation checks; a pointer update alone does not change the production app. Never blindly copy the submodule's package.json, startup adaptations or mock handlers into production behavior. The source paths match, making focused patches straightforward to apply.

Lynn's layout, styling and visual hierarchy take precedence when reconciling shared UI changes. Preserve working configuration, navigation and persistence behind that presentation. If her implementation introduces a functional regression, correct the behavior while retaining her visual design; for example, keep the toolbar-based Agent Canvas heading position when panels resize. Update layout assertions to match intentional design changes and retain checks for the underlying interactions. See experience alignment for the imported editor behavior.

ZIP exports

The repository-aligned ZIP, agent-studio-prototype-export.zip in the framework root, can be packaged from a clean standalone clone of the updated design repository. Include its .git directory and local framework-sync branch so designers retain the baseline and independent history after extracting it. Use git clone --no-local when cloning the embedded checkout for packaging; the archive must not depend on the framework's .git/modules or object store. Exclude installed dependencies, generated output and local environment files. Verify the clone's HEAD matches the published prototype revision before sharing.

export-repo.sh still creates agent-studio-prototype-export.zip in the root from the current framework app. That is a separate disposable snapshot, not an archive of unmerged designer changes. It refuses submodules, clones, dirty exports and non-disposable output directories. Never pass --out studio/design; use the sync helper above.

To distribute the designer repo's committed state directly, use its repository checkout or GitHub ZIP. GitHub ZIPs omit .git; use a clone when designers need to return commits. See prototype mode for runtime limitations and the handoff guide for documenting proposed APIs and backend work.

The September 28 reconciliation merges design main into feature/lynn-wip and fast-forwards design main to the tested result. The app import includes the conversation-count endpoint, version navigation in Activity, and disconnected save-state handling; see experience alignment.