Initialize your project

Initialization turns a clean clone into a buyer-owned development tree. It has one job before anything else: remove inherited identity and prove that the template is no longer pointing at someone else's app.

It then asks the product questions that an agent needs to work well: audience, problem, core loop, launch scope, platforms, inspiration, design direction, business model, activation event, growth hypothesis, and success metrics. The answers become the product, feature, roadmap, growth, key setup, and initialization-plan documents that the rest of the workflow reads.

The recommended path

clean clone
  → identity cleanup
  → product and growth interview
  → product, features, roadmap and Wire growth docs
  → service choices: MCP, manual, later or skip
  → buyer acceptance
  → validate acceptance
  → bounded feature work
  → .env and native prerequisites
  → prebuild and iOS or Android launch

Wire is part of the plan from the beginning. The initializer defines the activation event, lifecycle funnel, event map, first onboarding experiment, learning review, and optimization backlog. It is the growth system for experiments and analytics, not a later upsell paragraph.

Before you run it

You need a fresh checkout, Node and Yarn. Read the repository startup files first: AGENTS.md, CLAUDE.md, GEMINI.md, agents.md, or .cursorrules when the active host exposes them. Each adapter routes to ai_rules/project_init_workflow.md and the required project rules.

For a native launch, you will later need your own bundle identifier, Android package, URL scheme, Firebase files, app assets, and the environment values listed in .env.example. You can leave service credentials and assets pending during planning.

AI Pro testers should verify the exact reviewed candidate before changing anything:

git branch --show-current
git rev-parse HEAD

Expected starting commit for the pinned AI Pro tester flow: a7f6cb36f1fc3ecd8b3a7d9c8956afa30bf39984. Work on the tester branch you created from that commit.

Run planning first

The safest non-interactive form is:

node init.js --answers answers.json --no-native

Keep answers.json local and free of secrets. Use file paths for buyer Firebase files, never paste their contents into the JSON.

For an interactive run, use:

yarn init:project

The interactive prompts collect the identity and brand inputs, then continue with the product and growth interview. If you are not ready to prebuild, leave the final platform prompt blank or use the non-interactive --no-native form.

The answers.json file can contain these identity keys:

projectName, pitch, category, iosBundleIdentifier, androidPackage,
scheme, googleClientId, googleServicesJson, googleServiceInfoPlist,
theme, brandColorLight, brandColorDark, vibe, radius, iconSource, platform

It can also contain these planning keys:

audience, jobProblem, coreLoop, launchScope, platforms, inspiration,
designDirection, businessModel, activationEvent, growthHypothesis,
successMetrics, features, services

features is an array of buyer-owned feature objects. Each object may include name, scope, priority, and dependencies. services records only the selected mode and MCP availability. It never stores secret values.

What the initializer creates

The six canonical buyer documents are the source of truth. Memory is derived from accepted documents, not the other way around. Editing a canonical document or task after acceptance invalidates the acceptance digest and returns the state to planned.

Service setup is explicit

For each required service, choose mcp, manual, or later where that service supports it. Optional services may also be skip. Wire supports mcp, manual, or later, and cannot be skipped because the growth plan always needs a Wire workstream.

The initializer does not create accounts, call a service console, or infer a connection. mcp means the current host must actually expose the connector and produce a receipt. If it does not, the generated status remains manual_required. later remains pending. Never paste secret values into answers.json, planning documents, logs, or git.

Accept before feature work

Read all six documents and the task briefs. Confirm the product definition, MVP feature order, Wire growth plan, and service statuses with the buyer. Record acceptance by rerunning the same complete answers file with --accept:

node init.js --answers answers.json --no-native --accept

Then validate the recorded digest immediately before feature work:

node init.js --validate-init

Only explicit acceptance with a matching digest can authorize feature work. With no pending requirements, the accepted state is ready_for_feature_work. With pending services or assets, it remains initialized_with_pending. That state is honest and useful, but it does not authorize native launch.

If services or assets are still pending, run the source checks that do not claim identity or release readiness:

yarn type:check
yarn lint:check
yarn i18n:validate
yarn test:ci

After replacing the app assets, Firebase files, identity, and required provider configuration, run the complete fail-closed gate:

yarn validate

For the reviewed AI Pro candidate this covers type checking, linting, identity verification, and Jest. The accepted buyer replay passed 65 suites and 652 tests. yarn validate is expected to fail while required identity inputs are pending. A source-suite pass still does not prove a native build or provider connection.

After validation, the active host may assign the generated, dependency-ready task briefs to bounded subagents. The host must have those subagents available and must report receipts. The initializer itself does not launch Codex, Claude, Gemini, or any proprietary agent CLI.

Host adapters

The workflow is shared across coding hosts through the repository entry files:

These files describe a capability contract. They are not proof that a particular host, MCP connector, or subagent ran on your machine. Check the active host's exposed tools before delegating.

Native launch comes last

Before any prebuild or launch, create .env and replace placeholders with your own values:

cp .env.example .env

Follow Tool Integration for service setup, then First App Launch for the environment check and native commands. Do not use yarn web as a Standard buyer path. The app's supported validation and launch targets are native development builds.

When your environment and assets are ready, the native path is:

npx expo prebuild --clean
yarn ios       # macOS with Xcode
yarn android  # Android SDK and emulator or device

Run the identity verifier after prebuild:

yarn verify:identity

Restart Metro after adding or changing .env values. Expo reads public configuration when the bundle starts; a stale Metro process can make valid Wire or provider settings look absent.

Release readiness belongs to the release preflight and a real native build. Initialization, acceptance, and a green source test suite do not grant that status.

What the two testers should record

Each tester should keep a short, secret-free receipt with:

1. the tested commit and platform
2. initializer and yarn validate exit codes
3. the final initialization state
4. native build and first-launch result
5. one ordinary app or screen event visible in Wire
6. the instrumented activation event visible in Wire
7. the static onboarding fallback result with Wire configuration removed
8. any failed step with the exact command and first useful error

Do not record API keys, Firebase file contents, tokens, or signing credentials.

Recovery

The older U-AMOS pages are recovery material for projects that already have the template and need to repair one artifact. Start with the canonical workflow above, then use Product Description, Features List, Memory Bank, or Design System as needed.