kandev/docs/plans/empty-remote-repositories/task-05-document-empty-remote-workflow.md

id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design

id	title	status	wave	depends_on	plan	requirements	acceptance_criteria	system_design
05-document-empty-remote-workflow	Document the Empty Remote Workflow	done	5	04-prove-empty-remote-workflow	plan.md	REQ-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001 REQ-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002	AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.5 AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.1 AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.2 AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.3 AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.5 AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.8	../../specs/workspaces/system-design/empty-remote-repositories.md

Task 05: Document the Empty Remote Workflow

Summary

Update the public task how-to guides with empty-remote launch, first publication, credentials, and race recovery. Correct the stale local-repository initial-commit statement.

In scope

• Explain that task launch creates only a local empty baseline.
• Explain that Push or Create PR publishes the base before the task branch.
• Explain credential requirements and changed-remote recovery.
• Correct the local new-repository guide to describe its real empty initial commit.

Out of scope

• Add a new public page or navigation entry.
• Document implementation symbols or marker refs.
• Change screenshots.

Acceptance

• The how-to guides describe the launch and publication boundary without implementation terms.
• The recovery text tells users to reconcile a remote that another actor initialized.
• The local and remote empty-repository descriptions no longer contradict the product contract.

Verification

node --test scripts/validate-public-docs.test.mjs
node scripts/validate-public-docs.mjs
git diff --check -- docs/public

Files likely touched

• docs/public/tasks-and-workflows.md
• docs/public/use-kandev.md

Dependencies

• Task 04 proves the final user workflow that the guides describe.

Risks

• The current guide uses “empty repository” for both a local repository and an empty remote.
• Provider credentials differ between clone access and task runtime publication.

Parallelism

sequential

Inputs

• Empty-remote requirements and design.
• Public task workflow guides.
• Existing local-repository requirements.

Results

Completed. Updated the public task workflow and usage guides with the local-only launch boundary, credential requirements, base-first publication, and recovery behavior. Public documentation tests and validation passed (61 tests, 41 pages), with no whitespace errors.