Files
kandev/docs/plans/empty-remote-repositories/task-05-document-empty-remote-workflow.md
T
2026-08-31 03:26:51 +00:00

83 lines
2.6 KiB
Markdown

---
id: "05-document-empty-remote-workflow"
title: "Document the Empty Remote Workflow"
status: done
wave: 5
depends_on:
- "04-prove-empty-remote-workflow"
plan: "plan.md"
requirements:
- REQ-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001
- REQ-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002
acceptance_criteria:
- 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
system_design:
- ../../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
```bash
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.