Goal
Define and validate one canonical adopter path from installing Base to completing a verified project pull request.
Background
Base has a 90-second proof, onboarding commands, contributor guidance, and many capable subcommands. The breadth also creates early choices before a new adopter understands the core outcome. #930 improved the path for contributing to Base itself; it did not validate adoption of Base in an external project workspace.
The product should optimize for one observable result: a new user reaches a ready workspace, understands findings and trust, runs the project contract, and completes a verified project PR.
Scope
- Define the canonical install-to-first-project-PR journey for a new adopter.
- Cover clean macOS and supported Ubuntu/Debian source-checkout paths.
- Include workspace/project adoption, manifest creation or selection, trust review, setup/check/doctor, project validation, and PR readiness.
- Measure elapsed time, manual choices, failures, and documentation hops.
- Remove or defer unnecessary early choices through progressive disclosure.
- Use
base-demo where appropriate, then prove the path on at least one external-style project fixture.
Acceptance Criteria
- One documented path takes a new user from install to a verified project PR without private maintainer knowledge.
- macOS and Ubuntu/Debian differences are explicit and tested.
- The path has a target completion time and records observed results.
- Secondary commands and advanced profiles are progressively disclosed.
- Every failure point offers an actionable next command or document.
Validation
- Rehearse on clean or isolated macOS and Ubuntu/Debian environments.
- Record commands, timings, failures, and recovery steps.
- Validate all documented commands against the current release candidate.
- Add automated smoke coverage for deterministic portions.
git diff --check.
Non-Goals
- Do not make every Base feature part of first use.
- Do not optimize only for contributing to the Base repository.
- Do not hide trust or mutation decisions merely to shorten the path.
Project Fields
- Status: Backlog
- Priority: P1
- Size: M
- Area: Product
- Initiative: Adoption Polish
Agent Assignment
Human-led usability validation. Agents may automate deterministic smoke checks after the journey is defined.
Goal
Define and validate one canonical adopter path from installing Base to completing a verified project pull request.
Background
Base has a 90-second proof, onboarding commands, contributor guidance, and many capable subcommands. The breadth also creates early choices before a new adopter understands the core outcome. #930 improved the path for contributing to Base itself; it did not validate adoption of Base in an external project workspace.
The product should optimize for one observable result: a new user reaches a ready workspace, understands findings and trust, runs the project contract, and completes a verified project PR.
Scope
base-demowhere appropriate, then prove the path on at least one external-style project fixture.Acceptance Criteria
Validation
git diff --check.Non-Goals
Project Fields
Agent Assignment
Human-led usability validation. Agents may automate deterministic smoke checks after the journey is defined.