Repository navigation
Open
Labels
area: agentsSubagent roles and orchestrationSubagent roles and orchestrationcodex-firstCodex-first development scopeCodex-first development scopedocumentationImprovements or additions to documentationImprovements or additions to documentationgood first issueGood for newcomersGood for newcomers
Milestone
Description
Context
The parent-owned lifecycle model and SQLite journal are implemented and tested,
but contributors currently have to reconstruct phase rules, ownership, replay,
and the boundary between implemented and pending behavior from source and
several broad documents.
Outcome
Add one concise contributor guide explaining the lifecycle domain, legal phase
flow, parent-versus-worker ownership, persistence/replay model, artifact
references, cancellation/recovery semantics, and the implementation status that
exists on main when the documentation is merged.
Scope
- Document the legal
explore -> implement -> test -> review -> verify -> apply
sequence and terminal states. - Explain parent-owned transitions and the typed result each phase worker may
return. - Explain frozen profile, test-plan, source, budget, artifact, approval, and
state-digest identities. - Describe the SQLite event journal and deterministic replay with links to
source and focused tests. - Verify the status at merge time: distinguish the implemented domain/store from
whichever executor, read API, and timeline UI slices are still pending then. - Link the guide from existing architecture or verified-change documentation
without copying their full content.
Non-goals
- Changing Rust or TypeScript behavior, inventing future APIs, documenting
non-Codex execution, or presenting offline tests as provider-backed evidence. - A tutorial that performs provider calls or modifies a real worktree.
Acceptance criteria
- Every phase, terminal outcome, and ownership statement matches current
source and tests. - Implemented and pending lifecycle capabilities reflect
mainat merge
time, including any concurrently completed issue. - Source links target current files or symbols and avoid fragile line
numbers. - Existing architecture and verified-change documents link to the guide
without contradictory status text. -
git diff --checkpasses and manual review confirms every repository link
resolves.
Starting points
crates/needle-core/src/lifecycle.rscrates/needle-core/src/lifecycle/model.rscrates/needle-core/src/lifecycle/tests.rscrates/needle-runtime/src/store/lifecycles.rscrates/needle-runtime/src/store/lifecycles/tests.rsPROJECT_STATUS.md
Validation
Run git diff --check and verify each relative link against the current
checkout. No Cargo, frontend, provider, or workspace mutation is required for
this documentation-only issue.
Metadata
Metadata
Assignees
Labels
area: agentsSubagent roles and orchestrationSubagent roles and orchestrationcodex-firstCodex-first development scopeCodex-first development scopedocumentationImprovements or additions to documentationImprovements or additions to documentationgood first issueGood for newcomersGood for newcomers
Activity