109 lines
6.2 KiB
Markdown
109 lines
6.2 KiB
Markdown
# Project Lifecycle
|
|
|
|
## Status
|
|
|
|
- Status: active global workflow rule.
|
|
- Scope: all `video-workbench` projects, regardless of whether the final artifact is an MV, explainer video, slide-style presentation, or another visual/video package.
|
|
|
|
This document defines the common lifecycle. Project-specific files decide what each phase means for that medium.
|
|
|
|
## Lifecycle Phases
|
|
|
|
Use these phases in `projects/<project>/project.md`:
|
|
|
|
| Phase | Meaning | Common exit condition |
|
|
| --- | --- | --- |
|
|
| `intake-cleanup` | Accepted GPT / user source material is repaired, normalized, and stored under `intake/`. | Source files are readable, named, and mapped to local execution roles. |
|
|
| `system-definition` | Source material is localized into project production systems. | Local control files and production authorities exist. |
|
|
| `pilot-validation` | Core units, risky visual/audio rules, and workflow mechanics are tested. | The user accepts the core route and authorizes production. |
|
|
| `production` | Units are produced in batches through the approved route. | All target units are complete, accepted or explicitly deferred, and no active production package remains. |
|
|
| `assembly-closeout` | Produced assets are assembled, exported, reviewed for final use, and archived. | Delivery/output artifacts and handoff records are complete. |
|
|
|
|
The lifecycle phase is not the same as the operating line. A project in `production` can still temporarily use `test/audit` for a repair or failure investigation. A normal production package should use `production-light` after the route is approved.
|
|
|
|
## Medium-Specific Outputs
|
|
|
|
The phase names stay stable; the concrete work differs by medium.
|
|
|
|
| Medium | `system-definition` examples | `pilot-validation` examples | `production` examples |
|
|
| --- | --- | --- | --- |
|
|
| MV / shot-image package | `visual-system/`, style master, character registry, `slides/slides.md`. | Core shots, character consistency, reference-loading route, callback route. | Sequential slide image packages. |
|
|
| Explainer video | Script structure, terminology, visual explanation rules, voice style, asset taxonomy. | One short script section, key diagram, sample narration audio, timing check. | Script sections, diagrams, narration audio, supporting slides. |
|
|
| Slide-style presentation | Page system, component patterns, visual hierarchy, case/source map. | Representative pages and transition/page-density checks. | Page batches and export-ready assets. |
|
|
| Remotion video | Remotion style-system anchor, storyboard-to-component mapping, `projects/<project>/remotion/` source root, composition plan, render target. | Scaffold or existing source check, representative scene/component, `npx remotion still` or equivalent narrow render check, MP4 render route. | React/TypeScript source updates, scene/component batches, renderable MP4 outputs, render receipts. |
|
|
|
|
Do not copy GPT planning into duplicate project truth. The accepted `intake/` files remain sources; Codex-owned local execution rules live in `execution-plan.md`, `visual-system/`, `slides/`, `tasks/`, `remotion/` when applicable, and medium-specific control files.
|
|
|
|
## Production Run State
|
|
|
|
For any production request that may continue across multiple child sessions, create or update a lightweight run state file:
|
|
|
|
```text
|
|
projects/<project>/tasks/<task-id>/production-run-status.md
|
|
```
|
|
|
|
This file is the compression-safe continuation surface for unattended production. It should be short and current, not an audit report.
|
|
|
|
It records:
|
|
|
|
- project path;
|
|
- lifecycle phase;
|
|
- operating line;
|
|
- running mode;
|
|
- review mode;
|
|
- worker profile;
|
|
- package size or validation override;
|
|
- total target scope;
|
|
- completed units;
|
|
- Remotion source root, composition ID, render target, and render output path when applicable;
|
|
- active child session and callback target;
|
|
- next unresolved cursor;
|
|
- stop conditions;
|
|
- latest callback summary.
|
|
|
|
The parent session may be automatically compressed. After each child callback, the parent should reload the minimal source of truth before dispatching the next package:
|
|
|
|
```text
|
|
AGENTS.md
|
|
VIDEO_WORKBENCH.md
|
|
docs/workflows/project-lifecycle.md
|
|
docs/workflows/slide-task-orchestration.md
|
|
docs/workflows/slide-task-templates.md
|
|
projects/<project>/project.md
|
|
projects/<project>/execution-plan.md
|
|
projects/<project>/visual-system/visual-system.md
|
|
projects/<project>/slides/slides.md
|
|
projects/<project>/tasks/<task-id>/production-run-status.md
|
|
projects/<project>/tasks/<task-id>/task-log.md
|
|
```
|
|
|
|
Only read detailed prompts, images, old session records, or prior handoffs when the current handoff reports `blocked`, `failed`, `warning`, collision, ambiguous scope/status, or the user explicitly asks for inspection.
|
|
|
|
## Unattended Production Loop
|
|
|
|
When the user authorizes a full production run:
|
|
|
|
1. Resolve the target set from the project fact table.
|
|
2. Write `production-run-status.md` and `task-log.md`.
|
|
3. Dispatch exactly one clean child session for the next package.
|
|
4. Stop routine parent polling and wait for callback.
|
|
5. The child completes all artifact writes, `slides/slides.md` updates, compact closeout checks, and `child-session-handoff.md` before callback.
|
|
6. The callback is the child's final action. The child must not write or verify additional project files after a successful callback.
|
|
7. On callback, the parent reads the child handoff and updates the run state.
|
|
8. If status is clean and target units remain, dispatch the next package.
|
|
9. Stop only when the target set is complete or a stop condition is reached.
|
|
|
|
The parent does not need exact token/context usage to continue. It relies on file-backed reload after callback. A separate successor orchestration session is a fallback, not the default, and should be used only when the current parent cannot continue cleanly.
|
|
|
|
## Stop Conditions
|
|
|
|
Stop and ask the user when:
|
|
|
|
- a requested scope cannot be mapped cleanly;
|
|
- a package would include an already accepted unit unless explicitly requested;
|
|
- a target output path already exists and overwrite was not authorized;
|
|
- required references or production authority files cannot be loaded;
|
|
- child callback reports `blocked`, `failed`, or `warning`;
|
|
- user confirmation is explicitly required for the validation package result;
|
|
- the next action would change global package-size defaults or lifecycle rules.
|