Skip to content

Commit 3b380c8

Browse files
echowang1echowang1
committed
docs: add spec-first baseline with roadmap and executable tasks
1 parent 7e57640 commit 3b380c8

10 files changed

Lines changed: 427 additions & 5 deletions

‎README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,3 +28,11 @@ Private monorepo bootstrap for the AI short-drama production platform.
2828
- `docs/roadmap.md`
2929
- `docs/branch-protection.md`
3030
- `docs/sprints/sprint-01-backlog.md`
31+
- `docs/spec/README.md`
32+
- `docs/spec/tooling-positioning.md`
33+
- `docs/spec/master-roadmap.md`
34+
- `docs/spec/executable-task-list.md`
35+
36+
## Spec-First Rule
37+
- No sprint implementation starts before spec freeze.
38+
- Runtime progress must be tracked in `docs/spec/execution-ledger.md`.

‎docs/spec/README.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Cineweave Spec Index (Single Source of Truth)
2+
3+
This folder is the canonical source for project context and execution state.
4+
5+
## Reading Order (for fast context recovery)
6+
1. `docs/spec/project-background.md`
7+
2. `docs/spec/product-spec-v1.md`
8+
3. `docs/spec/tooling-positioning.md`
9+
4. `docs/spec/master-roadmap.md`
10+
5. `docs/spec/executable-task-list.md`
11+
6. `docs/spec/execution-ledger.md`
12+
7. `docs/spec/open-questions.md`
13+
8. `docs/sprints/sprint-01-backlog.md`
14+
15+
## Rules
16+
- Update spec docs before implementation starts.
17+
- Every scope change must update:
18+
- `product-spec-v1.md` (scope/acceptance)
19+
- `execution-ledger.md` (status/decision/log)
20+
- Keep entries short and timestamped.
21+
22+
## Status Vocabulary
23+
- `todo`
24+
- `in_progress`
25+
- `blocked`
26+
- `done`
27+
- `dropped`
28+
29+
## Ownership
30+
- Product owner maintains scope and acceptance.
31+
- Engineering owner maintains technical decisions and execution ledger.
32+
- QA owner maintains acceptance evidence links.

‎docs/spec/executable-task-list.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Executable Task List (Spec-First)
2+
3+
Use this list to create GitHub Issues directly.
4+
Status is tracked in `execution-ledger.md`.
5+
6+
## P0 - Must Start First
7+
8+
### SPEC-001 Freeze V1 Scope
9+
- Owner: Product
10+
- Status: todo
11+
- Acceptance:
12+
- `product-spec-v1.md` approved.
13+
- out-of-scope list signed off.
14+
15+
### SPEC-002 Freeze Tooling Positioning
16+
- Owner: Product + Eng
17+
- Status: todo
18+
- Acceptance:
19+
- `tooling-positioning.md` approved.
20+
- provider routing priority agreed (`Runway primary`, `Kling fallback`).
21+
22+
### EN-001 Shot State Machine Implementation
23+
- Owner: Backend
24+
- Status: todo
25+
- Acceptance:
26+
- supports `draft -> ready -> generating -> generated -> selected -> edited -> published`.
27+
- invalid transitions blocked.
28+
29+
### EN-002 Multi-Candidate Asset Model
30+
- Owner: Backend
31+
- Status: todo
32+
- Acceptance:
33+
- each shot allows multiple candidates.
34+
- exactly one primary selection.
35+
36+
### EN-003 Generation Task Queue Baseline
37+
- Owner: Backend
38+
- Status: todo
39+
- Acceptance:
40+
- task states persisted (`queued/running/succeeded/failed/cancelled`).
41+
- retries and error codes persisted.
42+
43+
### EN-004 Provider Adapter Contracts
44+
- Owner: Backend
45+
- Status: todo
46+
- Acceptance:
47+
- unified adapter interface.
48+
- `runway` and `kling` adapters both pass smoke flow.
49+
50+
### FE-001 Script Desk MVP
51+
- Owner: Frontend
52+
- Status: todo
53+
- Acceptance:
54+
- shot list with status/provider filters.
55+
- batch generate action.
56+
57+
### FE-002 Video Desk MVP
58+
- Owner: Frontend
59+
- Status: todo
60+
- Acceptance:
61+
- candidate preview and compare.
62+
- one-click candidate selection.
63+
64+
### QA-001 End-to-End Shot Flow
65+
- Owner: QA
66+
- Status: todo
67+
- Acceptance:
68+
- 20-shot scenario passes.
69+
- failed tasks retry successfully.
70+
71+
## P1 - Next Priority
72+
73+
### EN-005 Midjourney Tracking Layer
74+
- Owner: Backend
75+
- Status: todo
76+
- Acceptance:
77+
- prompt/result metadata tracked by shot.
78+
- manual import flow documented.
79+
80+
### FE-003 Image Desk MVP
81+
- Owner: Frontend
82+
- Status: todo
83+
- Acceptance:
84+
- per-shot image prompt records.
85+
- image asset linkage to shot.
86+
87+
### EN-006 CapCut Handoff Export Contract
88+
- Owner: Backend
89+
- Status: todo
90+
- Acceptance:
91+
- export includes ordered shot list, selected clips, subtitle draft, audio notes.
92+
- schema versioned.
93+
94+
### FE-004 Edit Desk MVP
95+
- Owner: Frontend
96+
- Status: todo
97+
- Acceptance:
98+
- export package generation UI.
99+
- pre-export checklist.
100+
101+
## P2 - Hardening
102+
103+
### SEC-001 Auth and Secret Baseline
104+
- Owner: Backend
105+
- Status: todo
106+
- Acceptance:
107+
- password hashing enabled.
108+
- provider keys encrypted at rest.
109+
110+
### OPS-001 Observability Baseline
111+
- Owner: DevOps
112+
- Status: todo
113+
- Acceptance:
114+
- task success rate and provider latency metrics.
115+
- alert rule for high fail rate.
116+
117+
### COST-001 Usage Guardrails
118+
- Owner: Backend + Product
119+
- Status: todo
120+
- Acceptance:
121+
- project-level quota threshold.
122+
- warning and block policy documented.
123+
124+
## Tracking Rule
125+
- Before coding: ensure corresponding spec items are approved.
126+
- After coding: update status and evidence link in `execution-ledger.md`.

‎docs/spec/execution-ledger.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Execution Ledger
2+
3+
Use this file as the progress ledger during delivery.
4+
5+
## Snapshot
6+
- Last updated: 2026-02-22
7+
- Current phase: Spec consolidation
8+
- Current sprint: Sprint 01 (not started)
9+
- Overall status: in_progress
10+
11+
## Milestones
12+
| ID | Milestone | Status | Owner | Due | Notes |
13+
|---|---|---|---|---|---|
14+
| M0 | Organization and repository bootstrap | done | Team | 2026-02-22 | `main/develop` ready, templates in place |
15+
| M1 | Spec baseline completed | in_progress | Product + Eng | 2026-02-23 | This document set is being finalized |
16+
| M2 | Sprint 01 implementation start | todo | Eng | TBD | Starts after spec freeze |
17+
18+
## Decision Log
19+
| Date | Decision | Owner | Rationale |
20+
|---|---|---|---|
21+
| 2026-02-22 | Use private repo and spec-first workflow | Team | Reduce drift and keep execution traceable |
22+
| 2026-02-22 | Use shot-level asset orchestration as MVP core | Team | Matches real AI short-drama workflow |
23+
| 2026-02-22 | Name project `cineweave-platform` | Team | Vendor-neutral and extensible branding |
24+
25+
## Task State Summary
26+
| Workstream | Status | Next Action |
27+
|---|---|---|
28+
| Governance docs | done | Keep synced with any process change |
29+
| Product spec | in_progress | Freeze V1 scope and acceptance |
30+
| Tooling positioning | in_progress | Confirm provider contracts and fallback constraints |
31+
| Master roadmap | in_progress | Confirm phase owner and target dates |
32+
| Executable task list | in_progress | Convert all P0/P1 tasks into issues |
33+
| Sprint backlog | done | Convert items into GitHub issues |
34+
| Engineering implementation | todo | Start after spec freeze |
35+
36+
## Change Log (execution)
37+
| Date | Change | Commit / Link |
38+
|---|---|---|
39+
| 2026-02-22 | Bootstrap governance and docs | `d35123a` |
40+
| 2026-02-22 | Rename repository context to Cineweave | `27d2110` |
41+
| 2026-02-22 | Add branch protection and Sprint 01 backlog docs | `7e57640` |
42+
| 2026-02-22 | Add spec index, tooling positioning, master roadmap, executable task list | pending |

‎docs/spec/master-roadmap.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Master Roadmap
2+
3+
## Objective
4+
Build a production-ready AI short-drama operating platform with human-in-the-loop editing.
5+
6+
## Phase Plan
7+
8+
### Phase 0: Spec and Governance Freeze (Now)
9+
- Status: in_progress
10+
- Deliverables:
11+
- Spec index and background complete.
12+
- Tooling positioning locked.
13+
- Sprint execution rules finalized.
14+
15+
### Phase 1: Shot Asset Hub MVP (2 Weeks)
16+
- Status: todo
17+
- Deliverables:
18+
- Shot state machine + candidate model.
19+
- Provider adapter baseline (Runway/Kling).
20+
- Script Desk + Video Desk usable MVP.
21+
- Batch retry and candidate selection flow.
22+
23+
### Phase 2: Editing Handoff and Quality Controls (2 Weeks)
24+
- Status: todo
25+
- Deliverables:
26+
- Edit Desk and CapCut handoff package.
27+
- Basic quality scoring and low-score replacement flow.
28+
- Progress and failure observability dashboard.
29+
30+
### Phase 3: Security and Reliability Hardening (2 Weeks)
31+
- Status: todo
32+
- Deliverables:
33+
- Auth hardening and key encryption at rest.
34+
- Cost guardrails and rate policy.
35+
- Incident runbook and alerting baseline.
36+
37+
### Phase 4: Multi-Project Scale Readiness (2-4 Weeks)
38+
- Status: todo
39+
- Deliverables:
40+
- Concurrency and queue performance tuning.
41+
- Cross-project usage analytics.
42+
- Release and rollback automation maturity.
43+
44+
## Exit Criteria per Phase
45+
- Phase 1 exit:
46+
- 20-shot workflow reproducible end-to-end.
47+
- fallback route verified.
48+
- Phase 2 exit:
49+
- Editor receives deterministic handoff package.
50+
- replacement loop reduces failed shots.
51+
- Phase 3 exit:
52+
- secrets and auth baseline enforced.
53+
- key operational alerts active.
54+
- Phase 4 exit:
55+
- stable multi-project operations under target load.
56+
57+
## Dependencies
58+
- Stable external provider APIs.
59+
- Team assignment for backend/frontend/QA.
60+
- Access to Runway/Kling/Midjourney operational accounts.

‎docs/spec/open-questions.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Open Questions and Blockers
2+
3+
## Product
4+
1. What is the exact deliverable format for CapCut handoff in Phase 1?
5+
2. Which publishing channels are mandatory for V1 (Douyin/Kuaishou/Xiaohongshu/YouTube)?
6+
3. What is the minimum acceptable generation success rate per project?
7+
8+
## Engineering
9+
1. Which task queue stack is preferred for V1?
10+
2. Should provider callbacks be supported in V1 or polling only?
11+
3. What retry policy is mandatory (max retries, cooldown)?
12+
13+
## Operations
14+
1. What are daily or per-project cost limits?
15+
2. Which monitoring platform will be used first (self-hosted or SaaS)?
16+
3. What incident SLA target applies for generation failures?
17+
18+
## Compliance
19+
1. Are there constraints for storing provider raw responses?
20+
2. Is prompt/content moderation required before generation starts?
21+
22+
## Resolution Rule
23+
- Each resolved item must be moved to `execution-ledger.md` decision log with date and owner.

‎docs/spec/product-spec-v1.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Product Spec V1
2+
3+
## 1. Product Scope
4+
5+
### In Scope (Phase 1)
6+
- Shot-level project orchestration.
7+
- Multi-candidate video generation per shot.
8+
- Provider routing for Runway/Kling.
9+
- Manual candidate selection and fallback rerun.
10+
- Export assistant for edit handoff (CapCut-ready metadata package in later phase).
11+
12+
### Out of Scope (Phase 1)
13+
- Full auto-editing.
14+
- Cross-project resource marketplace.
15+
- Enterprise-grade RBAC and billing.
16+
17+
## 2. User Roles
18+
- Creator: creates scripts and reviews generated assets.
19+
- Operator: runs batch generation, retries failures, and selects candidates.
20+
- Editor: final manual editing and publishing.
21+
22+
## 3. Domain Model (logical)
23+
- Project
24+
- Script
25+
- Shot
26+
- AssetCandidate
27+
- GenerationTask
28+
- ProviderConfig
29+
30+
## 4. Critical Workflow
31+
1. Import shot list from script.
32+
2. Mark shots as ready.
33+
3. Submit batch generation.
34+
4. Collect candidates from providers.
35+
5. Select one candidate per shot.
36+
6. Export selected sequence to editing workflow.
37+
38+
## 5. Acceptance Criteria (Phase 1)
39+
- A project supports 20+ shots in one run.
40+
- A shot supports multiple candidates and one selected result.
41+
- Failed tasks can retry and keep full error records.
42+
- Provider fallback works when primary provider fails.
43+
- Progress can be recovered from `execution-ledger.md` without chat history.
44+
45+
## 6. Quality Attributes
46+
- Traceability: every generated asset links to provider request/response metadata.
47+
- Recoverability: interrupted workflows can resume by task status.
48+
- Operability: operators can batch retry by filter.
49+
50+
## 7. Risks
51+
- External provider API instability.
52+
- Prompt quality variance causing low usable output.
53+
- Cost overrun without usage guardrails.
54+
55+
## 8. Mitigations
56+
- Adapter abstraction + provider fallback.
57+
- Quality scoring baseline in phase 2.
58+
- Per-project usage counters and alert thresholds.
59+
60+
## 9. Tooling Alignment
61+
This spec follows `docs/spec/tooling-positioning.md`:
62+
- LLM for script and shot prep.
63+
- Midjourney for still-image consistency.
64+
- Runway primary + Kling fallback for video generation.
65+
- CapCut as mandatory human editing endpoint.

‎docs/spec/project-background.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Project Background
2+
3+
## Why this project exists
4+
Cineweave aims to turn AI short-drama production into a repeatable pipeline:
5+
- AI generates fragmented assets.
6+
- Human editors curate and polish final output.
7+
8+
## Source workflow (validated)
9+
- Script and shot breakdown via LLM tools.
10+
- Character/scene image generation via Midjourney.
11+
- Image-to-video generation via Runway and Kling (fallback path).
12+
- Final editing and publishing via CapCut.
13+
14+
## Current baseline
15+
- Repository governance is initialized.
16+
- Branch protection is enabled on `main` and `develop`.
17+
- Sprint backlog exists, but implementation has not started.
18+
19+
## Core product direction
20+
- Build a shot-level asset operating system, not a single-model wrapper.
21+
- Keep provider integration pluggable.
22+
- Treat human takeover as a first-class path.
23+
24+
## Non-goals at current stage
25+
- One-click fully autonomous film production.
26+
- Multi-tenant enterprise permissions in first sprint.
27+
- Tight coupling to any single external vendor.

0 commit comments

Comments
 (0)