# Project Onboarding Workflow

**Status:** Approved target-state baseline — ProjectVision and GOLIVE semantics clarified by pre-run gap review  
**Full activation:** I2; minimal Project creation exists I1.

## Target State

Onboarding converts a new/existing software effort into an inspectable AWP Project without forcing users through a long classification form.

```text
Create / import Project
  -> identify new vs existing
  -> bind Repository/Repositories
  -> inspect available project evidence
  -> infer PlanningProfile + relevant traits
  -> detect current/documented/desired conflicts
  -> resolve only consequential owner questions
  -> generate/reconcile ProjectVision
  -> identify Connections/requirements
  -> create initial Project defaults/profile
  -> establish GOLIVE readiness projection
  -> enter Planning
```

The handoff intentionally produces both:

```text
ProjectVision
  what / why / for whom / enduring constraints

GOLIVE
  what remains before the declared launch/operational target is ready
```

Neither replaces the bounded `Plan` created through Planning.

## Existing Project Evidence

Inspect repository structure, docs/specs/plans, languages/dependencies, dev environment, tests/CI, release/deployment config, standards, provider references and current connections. Evidence has provenance/freshness.

Never collapse:

```text
Observed current state
Documented intended state
User-stated desired state
AWP recommendation
```

Conflicts become Findings/Decisions/OpenQuestions.

Repository `VISION.md` or equivalent product-direction documents are **evidence**, not automatically accepted AWP ProjectVision. AWP shows material conflict/provenance before acceptance.

## New Project

Use the user's description and accepted decisions to infer profile/traits. Auto-apply high/normal-confidence PlanningProfile with visible `Change`; do not stop onboarding to ask taxonomy questions that AWP can infer.

Generate an initial ProjectVision draft from the user-stated product intent and accepted owner decisions. Delegable technical inference may inform constraints, but AWP must not silently invent OwnerRequired product purpose/users/business commitments.

## ProjectVision Generation / Reconciliation

The onboarding Vision artifact includes where relevant:

```text
purpose / problem
primary users / jobs
intended outcomes
scope / major capabilities
non-goals
enduring constraints
material product principles
assumptions/evidence provenance
```

Flow:

```text
input/evidence
 -> draft ProjectVision
 -> surface material conflicts / low-confidence consequential inference
 -> resolve OwnerRequired items
 -> accept versioned ProjectVision
 -> feed PlanningProfile / ProjectPlanningDefaults / GOLIVE context
```

A later material Vision change creates a new version/superseding Decision. Onboarding never overwrites historical project intent silently.

Optional export/materialization to a repository `VISION.md` is a separate project policy/integration action. Existing repository content is never overwritten without an explicit reviewed change.

## Planning Mode

Project/user preference can default to Simple or Expert. Recommended initial substantial Plan may use Expert to establish reusable ProjectPlanningDefaults, then future Plans use Simple by default.

Mode selection is visible/changeable and never changes owner/policy authority classes.

## Connections

Missing provider access creates `ConnectionRequirement`. If needed immediately, connect in context. If deferrable, record requiredBy gate/consequence and continue.

OAuth/external auth returns to exact onboarding/Planning state.

## GOLIVE / Project Readiness

Onboarding establishes the first durable `GOLIVE` readiness projection for the Project using the accepted ProjectVision/target as context.

GOLIVE answers:

```text
what target are we trying to become ready for?
what gates are already satisfied?
what is blocked now?
what can be deferred safely?
what must exist before a later gate such as merge/release/production?
what evidence supports the current readiness state?
who/what owns each next action?
```

It is derived from authoritative ProjectVision/Project/Planning/Connection/Policy/Quality/Delivery state, not maintained as a second manually editable checklist.

Readiness states are:

```text
Ready
Ready with accepted/deferred gaps
Blocked
```

A deferred item records `blockingAt`, consequence, owner and revisit trigger. Onboarding may therefore finish even when a production-only connection or requirement is intentionally deferred.

Do not fake readiness with a generic completion percentage. A finite checklist/stat may support orientation, but blockers/consequences/gates remain primary.

## Invariants

- user does not re-enter evidence AWP can safely inspect;
- ProjectVision is generated/reconciled explicitly rather than omitted or inferred as disposable chat text;
- OwnerRequired product intent is never silently invented by AWP;
- existing repository Vision/docs are evidence, not automatic desired-state truth;
- low-confidence inference with materially different workflow consequences is surfaced;
- accepted Decisions/defaults/Vision versions are never silently deleted when profile changes;
- repository inspection is evidence, not desired-state truth;
- onboarding interruption is resumable;
- Project exists durably before long external/auth steps;
- no Connection secret is copied into project config;
- GOLIVE projection is recomputed from authoritative evidence/gates and can become stale explicitly;
- an onboarding shortcut never hides a later required gate.

## Reuse / Harvest Gate

Existing Project/onboarding/configuration helpers in Overdeck or Platform are inspected before equivalent generic onboarding mechanics are custom-built. Reuse may supply repository inspection/config/auth mechanics, but AWP owns ProjectVision, PlanningProfile, GOLIVE/readiness meaning and owner-decision semantics.

## Failure / Recovery

Repository inaccessible, provider degraded or auth cancelled leaves onboarding in recoverable attention state with previous Decisions/Vision draft intact. A failed evidence refresh preserves prior evidence with freshness/stale marker rather than silently deleting Vision/readiness state.

## Increment Realization

| Increment | Realization |
|---|---|
| I1 | create/select Project + Repository + minimal ProjectVision intent + minimal Plan entry; minimal dogfood readiness only. |
| I2 | full evidence inspection, ProjectVision generation/reconciliation, profile inference, defaults, connections and GOLIVE/Planning handoff. |
| I3–I8 | Decisions/policy/CI/delivery/incident gates can revise impact/readiness without replacing ProjectVision. |
| I9 | organization/tenant/customer onboarding extensions. |

## Current Implementation State

Target workflow; full onboarding product begins I2.

## Deferred Realization

Portfolio/org/project-template onboarding is later productization. Repository Vision export/synchronization is optional integration behavior, not required for ProjectVision identity.

## UI / Acceptance

User can create/import a project, inspect/accept a durable ProjectVision, understand inferred profile/evidence/conflicts, connect/defer access, resume after interruption, see a truthful gate-based GOLIVE readiness baseline, and reach Planning without needing to ask what remains.