# PRODUCT / UX · Agent Agency — Desktop v008 Owner-Approved Handoff v001

Status: **OWNER APPROVED**

APPROVED REFERENCE IMPLEMENTATION / SPECIFICATION:
- repository: `anpavel84-afk/agents`
- exact commit: `43d664e044d34f05bc7dc702c73c107f508ec539`
- reference path: `target-v2/prototype/desktop-v008/`
- artifact mirror: `https://files.anpavel.ru/Agency/Prototype/Desktop-v008/index.html`

Architecture baseline:
- **Target Architecture Delta v004 — unchanged**
- this handoff does not revise architecture
- mobile is explicitly deferred to a separate future Product/UX iteration

Implementation rule:
- Product/UX does **not** implement production from this handoff.
- PM · Agent Agency owns implementation planning / dispatch.
- Existing Target v004 implementation candidate must be **preserved and rebased/adapted** to the approved v008 specification.
- Do **not** restart Agent Agency from zero.
- Do **not** let Implementation invent missing UX.

## Approved Product/UX contract

Primary IA:
- outside Project: **Projects / Employee Library / New Project**
- inside Project: **Overview / Roadmap / Team**
- contextual surfaces: Task inspector / Result / Owner Attention / Employee & Profession detail / Execution planning / Discuss / Bootstrap proposal & provisioning

Approved desktop target:
- 1366–1920 px
- no page-level horizontal overflow
- human Owner layer first
- technical evidence secondary / collapsible
- long URLs, titles and Employee names must remain width-safe
- mobile is not part of this implementation acceptance gate

Approved future-state Product scope includes Target v004 functions that may not exist in current live UI:
- PM recommendation / Owner override / Mission request-selection / Actual Run as separate facts
- Automatic / Preferred / Exact
- truthful availability / capacity / freshness
- approved fallback + explicit fallback reason
- Exact unavailable → Owner decision
- same Task + same Mission + successor Run after runtime switch
- New Project Bootstrap + generic provisioning
- reusable Employees + global/project Drive workspaces
- Drive draft ≠ Hub approved ≠ Mission pinned snapshot
- Discuss + human collaboration endpoints
- optional Grok capability only when proven
- trusted-device session expectation

---

# WP0 — Data / truth reconciliation · P0

## Scope
Reconcile canonical and derived state before visual implementation can claim correctness:
- current Project stage/status/progress
- Team membership / responsibility / Task assignment
- Employee approved/adopted version
- Result / Artifact locators and accepted/unavailable state
- actual execution observation vs requested/planned execution

## Acceptance criteria
1. Projects, Overview and Roadmap show the same current stage and status from one canonical/derived contract.
2. Project progress and current-stage progress have documented denominators and do not contradict each other.
3. Team membership, effective responsibility and Task assignee/reviewer projections agree with canonical records.
4. Employee version shown as approved/adopted matches the actual project membership/version binding.
5. Accepted Result points to a durable verified Result/Artifact; unavailable/broken evidence is shown explicitly, not silently hidden.
6. Planned/requested runtime/model is never rendered as actual execution.
7. Data inconsistency remains a first-class explicit state until repaired; frontend does not cosmetically choose one conflicting value.
8. Existing Target v004 history/provenance is preserved.

# WP1 — Desktop shell / Projects / Overview · P1

## Scope
Rebase existing desktop shell into the approved Owner hierarchy and v008 visual/information model.

## Acceptance criteria
1. Outside Project navigation is Projects / Employee Library / New Project.
2. Inside Project navigation is Overview / Roadmap / Team.
3. Project card and Overview use human-readable descriptions, not import/SHA engineering copy.
4. Overview makes **NOW / NEXT / ATTENTION** understandable within approximately 3–5 seconds.
5. Overview shows Team preview, meaningful recent activity, Results, execution summary and Drive/workspace state without becoming a telemetry dashboard.
6. Technical provenance remains available but secondary.
7. 1366 and 1920 have zero page-level horizontal overflow.
8. Existing trusted-device/session persistence is not regressed.

# WP2 — Meaningful Roadmap + Owner-first Task inspector · P1

## Scope
Implement the v008 project-journey Roadmap and contextual Task inspector.

## Acceptance criteria
1. Roadmap reads top-to-bottom as meaningful human stages: completed → current → next → future.
2. Technical epochs (B0/B1/B6/B7 etc.) remain traceability metadata, not primary stage names.
3. Completed stage can show WHY / WHAT / WHO / RESULT / WHAT IT UNLOCKED.
4. Current and blocked/gated stages are visually distinct without turning Roadmap into a model-settings table.
5. Significant Tasks show one compact execution planning indicator.
6. Task inspector order is:
   - title/status
   - Owner summary: why + next action
   - Discuss / Result actions
   - responsible / planned / actual / result
   - execution planning
   - accepted Result
   - collapsed Technical details
7. Inspector width is bounded at approximately 520 px and never widens the page.
8. Long Task titles and technical locators wrap safely.

# WP3 — Results / Artifacts · P0/P1

## Scope
Replace raw-locator UX with human Result/Artifact actions.

## Acceptance criteria
1. Result card shows human title, type, short summary, state and source.
2. Primary actions use human verbs such as Open Result / GitHub / Artifact / Handoff.
3. Raw locator is secondary and safely wraps.
4. Accepted vs unavailable/broken state is explicit.
5. Result opened from Overview or Task resolves to the same canonical Result/Artifact.
6. Long URL / long artifact name never causes page-level horizontal overflow.

# WP4 — Team / Employee / Google Drive workspaces · P1

## Scope
Implement project staffing visibility and Drive workspace UX without conflating identity, membership or execution.

## Acceptance criteria
1. Employee identity, Project membership, responsibility and observed execution are visually separate.
2. Each Team card explains **why this Employee is in this Project**.
3. Team/Employee view shows project responsibility and current observed activity only when proven.
4. Approved Employee/profile version is visible.
5. Global Employee workspace and project-local workspace are clearly distinct.
6. Human actions are **Открыть рабочую папку** and **Открыть материалы проекта**; provider locators are not primary UI.
7. Drive draft changed, Hub approved version and project approved materials are separately visible.
8. Active Mission continues its pinned snapshot until explicit approved adoption/amendment.
9. Review candidate / Approve new version / Adopt in projects actions preserve architecture v004 + Drive review semantics.
10. Workspace blocked/unavailable state does not delete membership or fabricate readiness.

# WP5 — Employee Library + staffing flow · P1

## Scope
Implement the approved staffing/discovery experience.

## Acceptance criteria
1. Library exposes:
   - Готовые профессии
   - Мои сотрудники
   - Команда проекта
2. Human Russian categories and common aliases/synonyms work in search (e.g. QA/тестирование, Product/UX, архитектор, разработчик).
3. Search/filter does not render an unbounded wall of source templates.
4. Profession detail explains specialization, when to call, skills and reusable Employee matches.
5. Staffing flow is:
   **Need specialist → Profession → existing Employee check → Reuse OR Create → project role/workspace → Confirm membership.**
6. Existing reusable Employee is preferred over silent duplication.
7. Adding to Project creates membership/context/workspace binding, not a duplicate global Employee.
8. Existing member does not get a misleading duplicate “Add” action.

# WP6 — New Project Bootstrap + generic provisioning · P1

## Scope
Implement the approved Target v004 onboarding UX using existing architecture contracts.

## Acceptance criteria
1. Flow is:
   **Sources → adaptive Interview / Understanding → exact Bootstrap Proposal → Owner approval → Provisioning → Ready / Project Control.**
2. No external provisioning effects occur before approval of the exact proposal/package revision.
3. Proposal shows:
   - project understanding
   - scope/non-goals
   - proposed Team
   - reused/new Employees
   - initial Roadmap
   - Drive/workspace plan
   - execution policy
   - PM execution recommendations
   - explicit Owner overrides
   - integrations/runtime bindings
   - collaboration endpoints
   - only real manual Owner actions
4. Provisioning Owner states are:
   - Настраивается автоматически
   - Готово
   - Ожидается действие владельца
   - Заблокировано
5. Normal Owner UI does not expose Bridge / journal / workRoot / Windows service mechanics.
6. Optional provider/chat setup does not block Project readiness when not required for initial admitted capabilities.
7. Unverified adapter/capability remains unavailable/manual, never green.
8. Existing v004 setup_operations / provisioning architecture is reused; no new workflow engine is invented.

# WP7 — Execution planning / fallback / runtime switch · P1

## Scope
Implement Target v004 execution-selection semantics exactly as approved in v008.

## Acceptance criteria
1. Four facts remain independent:
   - PM recommendation
   - Owner Task preference/override
   - Mission request / selected option
   - Actual Run runtime/model/effort observation
2. Task preference survives reload/restart and changes future Mission planning only.
3. PM recommendation can change without overwriting Owner override.
4. “Вернуть рекомендацию PM” clears only Owner override.
5. Automatic / Preferred / Exact are visibly distinct:
   - Automatic uses recommendation/approved defaults
   - Preferred allows only approved fallback
   - Exact forbids silent fallback
6. Selector truthfully represents:
   - Available
   - Unavailable
   - Unknown
   - Stale
   - Unsupported
   - capacity state
   - observation freshness
7. Option presence in selector is not proof of availability.
8. Unsupported Exact model/effort is blocked with an explicit reason.
9. Fallback state preserves:
   - requested preference
   - selected Mission option
   - actual Run
   - human fallback reason
10. Owner Attention is created when Exact cannot proceed and a real Owner decision is required.
11. Mid-Mission runtime switch preserves:
   - same Task
   - same Mission
   - historical predecessor Run
   - checkpoint/provenance
   - new successor Run
12. Human copy states **«Исполнение продолжено в другой среде»**.
13. Generation/fence/checkpoint internals stay under Advanced.
14. Actual runtime/model/effort comes only from verified observation; requested configuration is never substituted.

# WP8 — Discuss / collaboration endpoints · P1

## Scope
Implement external conversation routing without turning Hub into chat.

## Acceptance criteria
1. Task / Owner Attention / eligible Candidate can expose **Обсудить**.
2. UI shows human destination before opening:
   - PM · Agent Agency
   - Product / UX · Agent Agency
   - ARCH · Agent Agency
   - other admitted Employee / Project Home
3. Context packet is shown/copied separately from opening conversation.
4. If prefill is unavailable, CTA becomes **Открыть + Скопировать контекст**.
5. Technical chat/native locators are not primary content.
6. Discussion itself never mutates Task/Decision/Hub canonical state.
7. Existing v004 collaboration-endpoint architecture is reused.

# WP9 — Trusted-device authentication completion · P2

## Scope
Complete accepted Owner session UX around existing auth/session behavior.

## Acceptance criteria
1. Trusted device expectation is:
   **PIN + OTP once → normal persistent session**.
2. Ordinary reload/new tab does not request PIN+OTP again without a security reason.
3. Explicit Logout revokes the current session as designed.
4. Security expiry/revocation produces a clear re-auth state.
5. Expired/untrusted session cannot silently continue privileged Owner actions.
6. Auth UX does not regress the already verified current-session persistence.
7. Full-browser/session-expiry/logout QA is documented.

# WP10 — Independent QA / Product acceptance gate

## Scope
Verify the implementation against the Owner-approved v008 specification and Target v004 future-state matrix.

## Acceptance criteria
1. Re-run browser QA at 1366 and 1920.
2. Zero page-level horizontal overflow in:
   - normal
   - long-content
   - unavailable/error
   - data-inconsistency states
3. Task inspector remains width-bounded.
4. Long URL/title/Employee names remain safe.
5. Owner layer is human-first; technical details remain secondary.
6. Execution planning covers Automatic/Preferred/Exact, availability/capacity/freshness, fallback, Exact-unavailable and successor Run.
7. Bootstrap covers Sources → Interview → Proposal → Approval → Provisioning.
8. Team/Drive covers draft vs approved vs pinned snapshot.
9. Discuss routing is non-mutating and destination-aware.
10. Grok remains optional and truthful; unavailable/unverified is not green.
11. Data inconsistency is surfaced, not prettified.
12. QA cites the exact implemented candidate revision and exact approved Product/UX reference commit.
13. Any deviation from v008 requires explicit Product/UX/Owner review before acceptance.

---

## Reference freeze

The approved Product/UX reference is immutable and pinned to:

`43d664e044d34f05bc7dc702c73c107f508ec539`

Any later repository commits that only record approval status / handoff metadata do **not** replace the approved reference implementation/specification unless Human Owner explicitly approves a newer Product/UX reference.

## PM status

**OWNER APPROVED**

PM · Agent Agency may now plan/dispatch implementation within the approved scope, while preserving architecture v004 and rebasing the existing implementation candidate rather than rebuilding the product.

Product/UX does not perform production implementation from this handoff.


## Approval record

- Human Owner approval received: **2026-09-19**
- Product/UX status: **OWNER APPROVED**
- Approved immutable desktop reference: `43d664e044d34f05bc7dc702c73c107f508ec539`
- Mobile: **deferred to a separate future Product/UX iteration**
- Architecture: **Target v004 unchanged**
- Production implementation by Product/UX: **not performed**
- Implementation ownership: **PM · Agent Agency**
- Controlling implementation scope: **WP0–WP10 in this handoff**