diff --git a/docs/README.md b/docs/README.md index 71111a5..ea0eeb8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -33,5 +33,6 @@ Projects installed with v0.4.1 that report `Unrecognized key: rules` should foll * [Contributing Guidelines](09-contributing/contribution-overview.md) * [Real-World Examples and Tutorials](10-examples/README.md) * [Appendices and Traceability](11-appendices/glossary.md) +* [Product Evidence and Public Demonstration](../marketing/README.md) For the complete page tree, see [SUMMARY.md](SUMMARY.md). diff --git a/marketing/README.md b/marketing/README.md new file mode 100644 index 0000000..c929918 --- /dev/null +++ b/marketing/README.md @@ -0,0 +1,101 @@ +# Product Evidence and Public Demonstration + +This section defines how Development Kit should prove its value publicly through real screenshots, short demonstrations, a complete product video, and investor-facing evidence. + +## Objective + +The evidence system must answer four questions quickly: + +1. What problem does Development Kit solve? +2. What does the product actually do inside a supported coding agent? +3. What controls prevent unsafe or unverified automation? +4. What measurable engineering assets and validation systems support the product claim? + +## Audience tracks + +### Public and prospective users + +Show that installation is simple, the recommended workflow is understandable, and the product guides users without requiring them to memorize every command. + +Primary evidence: + +- Quick installation animation +- OpenCode startup menu screenshot +- 90-second overview video +- Clear link to the public npm package + +### Developers and technical evaluators + +Show deterministic lifecycle state, specialist routing, approval gates, tests, evaluations, and release validation. + +Primary evidence: + +- Autopilot lifecycle status screenshot +- Approval-gate screenshot +- Release-validation screenshot +- Technical walkthrough with commands visible +- Links to runtime, tests, evaluations, and architecture documentation + +### Potential investors and strategic partners + +Show the category problem, differentiated workflow architecture, product defensibility, repeatability, and evidence that Development Kit is a maintained public product rather than a prompt collection. + +Primary evidence: + +- Two-minute investor narrative +- Architecture and workflow diagram +- Current component and validation metrics +- Public npm and GitHub release proof +- Roadmap and adoption instrumentation plan + +## Evidence hierarchy + +Use the following order on public pages: + +1. One strong hero screenshot or clickable demo thumbnail +2. One short animated demonstration +3. Three to five focused screenshots with outcome captions +4. One full product walkthrough +5. Technical proof links and validation metrics +6. Investor narrative and roadmap material + +Do not overload the root README with every asset. The README should create understanding and confidence quickly, then link to a deeper showcase page. + +## Required deliverables + +- [Capture and publish checklist](capture-and-publish-checklist.md) +- [Capture plan](capture-plan.md) +- [Repeatable demo project](demo-project-brief.md) +- [Video storyboard and narration](video-storyboard.md) +- [Investor demonstration narrative](investor-demo-narrative.md) +- [README showcase template](readme-showcase-template.md) +- [Recording and privacy checklist](recording-checklist.md) +- [Product showcase structure](product-showcase.md) +- [Media standards](../media/README.md) + +## Acceptance criteria + +The first evidence release is ready when: + +- Five canonical screenshots exist and use consistent dimensions and styling. +- Two short repository-friendly demonstrations exist. +- A captioned 60 to 90 second public overview video is hosted at a stable URL. +- The root README contains a concise `See Development Kit in action` section. +- The showcase page explains each function using real output. +- All assets are free of secrets, private repository data, personal notifications, and unrelated account information. +- Every claim shown in a caption is supported by the displayed product state or linked source documentation. +- The documentation and link validators pass. + +## Success measures + +After publication, track: + +- README-to-demo click-through rate +- Demo completion rate +- Repository stars and forks +- npm downloads +- Issue and discussion quality +- Installation failures reported by environment +- Conversion from demo viewers to repository visitors or package users + +These measures should be introduced only after a privacy-conscious analytics approach is approved. diff --git a/marketing/capture-and-publish-checklist.md b/marketing/capture-and-publish-checklist.md new file mode 100644 index 0000000..39f543d --- /dev/null +++ b/marketing/capture-and-publish-checklist.md @@ -0,0 +1,106 @@ +# Capture and Publish Checklist + +Use this checklist to complete the first Development Kit public evidence release. Keep the pull request in draft until every required gate is complete. + +## 1. Record the evidence environment + +- [ ] Use the dedicated `RelayBoard` demo workspace described in [the demo project brief](demo-project-brief.md). +- [ ] Restore the clean starter commit and remove previous `.development-kit` state. +- [ ] Confirm the workspace contains only synthetic data. +- [ ] Record the Development Kit, OpenCode, Node.js, and operating-system versions. +- [ ] Record the starter repository commit, capture date, and exact commands used. +- [ ] Record every crop, annotation, redaction, shortened sequence, or speed change. +- [ ] Complete an unrecorded rehearsal, reset the workspace, and then make the final captures. + +## 2. Capture the five canonical screenshots + +- [ ] `media/screenshots/npm-installation.png` + - Run `npm view development-kit version`. + - Run `npx development-kit@0.4.2 init --opencode --dry-run`. + - Show the public version and generated file plan. + - Export as a 1600 x 900 PNG. +- [ ] `media/screenshots/opencode-startup-menu.png` + - Open the clean demo workspace in OpenCode. + - Show the recommended Development Kit guided-workflow entry. + - Export as a 1600 x 900 PNG. +- [ ] `media/screenshots/autopilot-lifecycle-status.png` + - Start `/dk-autopilot`. + - Show the current lifecycle stage, selected action, and next transition. + - Export as a 1600 x 900 PNG. +- [ ] `media/screenshots/approval-gate.png` + - Reach a safe approval boundary for a push, pull request, release, or publication action. + - Show the explicit authorization request without executing a real consequential operation. + - Export as a 1600 x 900 PNG. +- [ ] `media/screenshots/release-validation.png` + - Run `npm run release:validate` from the Development Kit repository. + - Show the final passing framework, plugin, documentation, OpenCode, Autopilot, and evaluation summary. + - Export as a 1600 x 900 PNG. + +## 3. Produce the short demonstrations + +- [ ] `media/demos/quick-install.webp` + - Show the npm version query, OpenCode dry run, and generated file plan. + - Target 10 to 15 seconds, with readable captions, under 8 MB. +- [ ] `media/demos/autopilot-overview.webp` + - Show OpenCode startup, the guided entry, `/dk-autopilot`, lifecycle selection, an approval pause, and state evidence. + - Target 20 to 35 seconds, with readable captions, under 10 MB. + +Cut both demonstrations from the same reviewed master recording where practical so commands, versions, and visual treatment remain consistent. + +## 4. Publish the full demonstration + +- [ ] Edit the reviewed master recording to 75 to 90 seconds. +- [ ] Use real Development Kit execution for every product scene. +- [ ] Add captions and a written transcript. +- [ ] Keep commands and outcomes readable at normal playback size. +- [ ] Disclose materially shortened or accelerated sequences. +- [ ] End with the repository, npm package, and captured version. +- [ ] Publish to a stable public URL that works without authentication. +- [ ] Retain the unedited source recording privately for authenticity review. + +## 5. Produce the promotional artwork + +- [ ] `media/social/product-demo-thumbnail.png` + - Use a real product capture as the interface background. + - Add Development Kit branding, a play icon, and `Watch the 90-second demo`. + - Export as a 1280 x 720 PNG. +- [ ] `media/social/repository-preview.png` + - Include the product name, concise value proposition, nine-stage lifecycle, supported environments, and captured public version. + - Use real product imagery wherever an interface is shown. + - Export as a 1280 x 640 PNG under 1 MB. + - Configure it as the GitHub repository social-preview image. + +## 6. Review privacy, accuracy, and authenticity + +Complete [the recording and privacy checklist](recording-checklist.md), including these release blockers: + +- [ ] All displayed output comes from real execution. +- [ ] Commands and versions match the public release. +- [ ] No secret, token, API key, email address, private URL, account detail, notification, or unrelated repository is visible. +- [ ] No unnecessary personal filesystem path is visible. +- [ ] Cropping does not hide warnings, failures, or relevant context. +- [ ] Annotations do not alter the underlying evidence. +- [ ] Captions make only claims supported by the visible evidence. +- [ ] Approval gates are shown accurately and are not bypassed. +- [ ] Every image has concise descriptive alt text. +- [ ] A separate second review has checked privacy and accuracy. + +## 7. Activate the public documentation + +- [ ] Replace planning language in [the product showcase](product-showcase.md) with the reviewed evidence, captions, captured version, capture date, and supporting links. +- [ ] Replace `PUBLIC_VIDEO_URL` in [the README showcase template](readme-showcase-template.md) with the verified public video URL. +- [ ] Remove the intentional spaces from the inactive Markdown in the template. +- [ ] Insert the activated `See Development Kit in action` section into the root README after `Current release` and before `What you get`. +- [ ] Verify the documentation-home link to this marketing workspace. +- [ ] Verify every image, animation, video, documentation, npm, and GitHub link. +- [ ] Confirm that no placeholder URL, inactive Markdown, broken reference, or `coming soon` claim remains. + +## 8. Run the final merge gate + +- [ ] Run `npm run release:validate` against the final asset commit. +- [ ] Confirm the entire suite passes. +- [ ] Confirm large master video files are not committed or included in the npm package. +- [ ] Record the final evidence metadata and validation result in the pull request. +- [ ] Request final evidence review. +- [ ] Mark the pull request ready only after all preceding gates pass. +- [ ] Merge only after the evidence, privacy, accuracy, links, and validation results are approved. diff --git a/marketing/capture-plan.md b/marketing/capture-plan.md new file mode 100644 index 0000000..3be1d1f --- /dev/null +++ b/marketing/capture-plan.md @@ -0,0 +1,119 @@ +# Evidence Capture Plan + +## Demo workspace + +Use a dedicated folder such as: + +```text +C:\Users\SSTECH\developments\dk-public-demo +``` + +The workspace should contain only files created for the demonstration. Do not use customer repositories, personal projects, production credentials, or private documents. + +## Preparation + +1. Update Development Kit and confirm the public package version. +2. Use the current stable OpenCode release. +3. Set the display to 1920 x 1080 where practical. +4. Use a readable editor and terminal font size, typically 18 to 22 px. +5. Disable notifications and hide bookmarks, personal tabs, account details, and taskbar items that reveal unrelated information. +6. Use a consistent light or dark theme across all captures. +7. Clear terminal history where it could expose private paths or commands. +8. Prepare a small, neutral demo project such as a task-tracking API or simple dashboard. + +## Capture sequence + +### Capture 1: Public npm installation + +Show: + +```powershell +npm view development-kit version +npx development-kit@0.4.2 init --opencode --dry-run +``` + +Evidence goal: Development Kit is publicly available and the installation plan is understandable before files are written. + +Output assets: + +- `media/screenshots/npm-installation.png` +- `media/demos/quick-install.webp` + +### Capture 2: OpenCode startup experience + +Open the demo workspace in OpenCode and capture the Development Kit recommended startup option. + +Evidence goal: The user can enter the complete workflow without learning every command first. + +Output asset: + +- `media/screenshots/opencode-startup-menu.png` + +### Capture 3: Autopilot lifecycle state + +Start: + +```text +/dk-autopilot +``` + +Capture the current lifecycle stage, selected action, and the transition to the next stage. + +Evidence goal: Development Kit coordinates a defined lifecycle rather than producing an unstructured response. + +Output assets: + +- `media/screenshots/autopilot-lifecycle-status.png` +- `media/demos/autopilot-overview.webp` + +### Capture 4: Human approval gate + +Use a safe demonstration action that reaches a consequential approval boundary, such as preparing a pull request, release, or remote push without executing it automatically. + +Evidence goal: Development Kit stops for explicit authorization before consequential operations. + +Output asset: + +- `media/screenshots/approval-gate.png` + +Do not demonstrate approvals using real production credentials or a repository where accidental execution would be harmful. + +### Capture 5: Verification evidence + +From the Development Kit source repository, show: + +```powershell +npm run release:validate +``` + +Capture the final summary showing the framework, documentation, OpenCode, Autopilot, and evaluation gates passing. + +Evidence goal: Product claims are backed by automated validation. + +Output asset: + +- `media/screenshots/release-validation.png` + +## Optional advanced captures + +- Pause and resume across sessions +- Stale artifact detection after an upstream change +- Rejection of an invalid approval token +- Recovery from an interrupted action lease +- Manual command fallback from `/dk-autopilot` +- Antigravity installation and startup experience +- GitHub release and npm publication workflow + +## Capture order + +Capture static screenshots first. Then record the full video in one continuous session using the same workspace and visual settings. The short animations should be cut from the full recording so the evidence remains consistent. + +## Review before publication + +A second review should verify: + +- Commands and version numbers are correct. +- No secret, email, username, private path, browser profile, or unrelated repository is visible. +- Captions describe only what the image proves. +- The workflow shown matches current documentation. +- The recording does not imply that approval gates were bypassed. diff --git a/marketing/demo-project-brief.md b/marketing/demo-project-brief.md new file mode 100644 index 0000000..9b31e61 --- /dev/null +++ b/marketing/demo-project-brief.md @@ -0,0 +1,71 @@ +# Repeatable Demo Project Brief + +Use one neutral, disposable project for all public Development Kit demonstrations so screenshots and videos remain consistent across releases. + +## Project concept + +Build a small issue-tracking service named `RelayBoard`. + +The demo request is: + +> Add a project status endpoint that returns application health, current version, and the number of open work items. Include tests, documentation, and safe release preparation. + +This request is intentionally small enough for a public demonstration while still exercising discovery, specification, design, planning, implementation, verification, review, simplification, and completion. + +## Suggested starting repository + +```text +relayboard-demo/ +├── package.json +├── src/ +│ ├── app.js +│ └── work-items.js +├── test/ +│ └── work-items.test.js +└── README.md +``` + +Use only synthetic data. + +## Demonstration goals + +The demo should visibly show Development Kit: + +1. Inspecting the existing repository before editing +2. Clarifying the required endpoint and acceptance criteria +3. Producing the minimum necessary specification +4. Creating a small implementation plan +5. Selecting a focused implementation task +6. Running or requesting tests +7. Reviewing specification compliance and code quality +8. Simplifying unnecessary complexity +9. Stopping for approval before any remote or release action + +## Safety boundary + +Use a local-only repository or a dedicated public demo repository with no production deployment, credentials, customer data, or protected resources. + +Do not configure a real deployment target for the recording. A release or push approval gate may be demonstrated without completing the remote action. + +## Reset procedure + +Before each recording: + +1. Delete the previous demo workspace. +2. Restore the clean starter repository. +3. Confirm no `.development-kit` state remains from a prior run. +4. Confirm the current Development Kit version. +5. Run the intended capture sequence once without recording. +6. Reset again and begin the final recording. + +## Reproducibility record + +The pull request that adds each evidence set should record: + +- Starter repository commit +- Development Kit version +- OpenCode version +- Node.js version +- Operating system +- Commands executed +- Any edited or accelerated sections diff --git a/marketing/investor-demo-narrative.md b/marketing/investor-demo-narrative.md new file mode 100644 index 0000000..f5731a3 --- /dev/null +++ b/marketing/investor-demo-narrative.md @@ -0,0 +1,113 @@ +# Investor and Strategic Partner Demonstration + +## Purpose + +This narrative is designed for a two to three minute product demonstration. It should explain the market problem, differentiated architecture, proof of execution, and credible next-stage opportunity without overstating traction or claiming metrics that have not been measured. + +## Positioning + +Development Kit is an execution and governance layer for AI-assisted software development. It gives coding agents a structured lifecycle, specialist roles, persistent state, automated verification, and explicit human approval boundaries. + +It is not positioned as another general chat interface, code generator, or project-management dashboard. + +## Demonstration sequence + +### 1. Category problem + +Show a typical unstructured AI coding request moving directly from a vague requirement into implementation. + +Message: + +AI development tools can generate code quickly, but teams still need a repeatable way to control requirements, architecture, task scope, verification, review, and consequential operations. + +### 2. Product entry point + +Show the OpenCode recommended workflow and start `/dk-autopilot`. + +Message: + +Development Kit provides one guided entry point that determines the correct lifecycle stage and activates the relevant command, agent, and skills. + +### 3. Workflow architecture + +Show the nine-stage lifecycle and persistent state. + +Message: + +The workflow is not a single prompt. It is an executable lifecycle with persistent state, deterministic next actions, policy checks, staleness detection, and recovery behaviour. + +### 4. Human control + +Show an approval gate before a consequential action. + +Message: + +The product is designed for controlled automation. Remote pushes, merges, releases, deployments, package publication, destructive changes, and security-risk acceptance require explicit human approval. + +### 5. Technical proof + +Show the release validation summary and repository structure. + +Message: + +The current public release includes 13 workflow commands, 18 specialist agents, 43 engineering skills, an Autopilot runtime, automated documentation validation, unit tests, and behavioural evaluation scenarios. + +### 6. Public distribution + +Show GitHub Releases and the npm package. + +Message: + +Development Kit is publicly distributed through GitHub and npm, creating a direct path for developer testing, contribution, and ecosystem feedback. + +## Differentiation + +Emphasize these distinctions: + +- Lifecycle orchestration rather than isolated prompting +- Persistent and inspectable workflow state +- Specialist role routing +- Explicit approval and cancellation controls +- Artifact staleness and downstream invalidation +- Verification before completion claims +- Open integration with supported coding-agent environments +- Public tests, evaluations, and documentation + +## Defensibility narrative + +Use careful language. The defensible asset is not a single prompt. It is the combined operating model: + +- Lifecycle and transition architecture +- Policy and approval system +- Agent and skill library +- Evaluation corpus +- Documentation and release discipline +- Integration knowledge across supported environments +- Future usage data and workflow outcome benchmarks, once collected with appropriate privacy controls + +## Current evidence versus future evidence + +### Evidence available now + +- Public GitHub repository +- Public npm package +- Versioned releases +- Defined lifecycle and component inventory +- Automated test and validation suites +- Real OpenCode and terminal demonstrations + +### Evidence still required + +- Active-user and retention measurements +- Installation conversion rates +- Workflow completion rates +- Time-to-completion comparisons +- Defect or rework reduction studies +- Enterprise pilot evidence +- Revenue or commercial demand evidence + +Do not imply that future evidence already exists. + +## Closing statement + +Development Kit is building the workflow and governance layer that helps AI coding agents operate more like disciplined software-engineering teams. The current public release proves the architecture and distribution model. The next stage is to validate adoption, workflow outcomes, and commercial demand through real users and targeted pilots. diff --git a/marketing/product-showcase.md b/marketing/product-showcase.md new file mode 100644 index 0000000..1dd3016 --- /dev/null +++ b/marketing/product-showcase.md @@ -0,0 +1,60 @@ +# Development Kit Product Showcase + +This page is the planned long-form evidence walkthrough for Development Kit. It should be published only after the canonical screenshots and full product video have been captured and reviewed. + +## What the showcase must prove + +- Public installation from npm +- Correct OpenCode integration +- Recommended automated workflow entry +- Nine-stage lifecycle orchestration +- Persistent and recoverable workflow state +- Explicit human approval boundaries +- Automated release validation +- Public GitHub and npm distribution + +## Evidence sequence + +### 1. Install and inspect before writing + +Show the current npm version and an OpenCode dry run. + +Claim supported: users can inspect the intended file changes before installation. + +### 2. Start with one guided entry point + +Show the recommended startup option and `/dk-autopilot`. + +Claim supported: users do not need to memorize the complete command library before beginning. + +### 3. Move through a defined lifecycle + +Show the current stage, selected action, and state transition. + +Claim supported: Development Kit coordinates work through an explicit software-development lifecycle. + +### 4. Preserve human control + +Show a real approval request for a safe demonstration operation. + +Claim supported: consequential actions require explicit authorization. + +### 5. Validate before release + +Show the final `npm run release:validate` summary. + +Claim supported: framework structure, documentation, OpenCode configuration, Autopilot behaviour, and evaluation scenarios are checked automatically. + +## Evidence caption format + +Every screenshot or clip should include: + +1. A direct title +2. One sentence describing the action +3. One sentence describing the outcome +4. The Development Kit version +5. A link to the related documentation or source file + +## Publication gate + +Do not publish this page as a product proof page until all referenced evidence exists. The final version must replace planning language with real captures, captions, version notes, and a stable full-video link. diff --git a/marketing/readme-showcase-template.md b/marketing/readme-showcase-template.md new file mode 100644 index 0000000..4795d34 --- /dev/null +++ b/marketing/readme-showcase-template.md @@ -0,0 +1,47 @@ +# README Product Showcase Template + +Use this section in the root README only after the referenced assets and public video URL exist. + +The example below intentionally places spaces between Markdown link tokens so validation does not treat inactive asset paths as live links. Remove those spaces only after every asset has been captured, reviewed, and committed. + +```text +## See Development Kit in action + +[ ![Watch the Development Kit product demo] (media/social/product-demo-thumbnail.png) ] (PUBLIC_VIDEO_URL) + +**Watch the 90-second product overview** to see installation, the guided OpenCode entry experience, `/dk-autopilot`, persistent lifecycle state, human approval gates, and release validation. + +### Guided workflow + +! [OpenCode showing the recommended Development Kit automated guided workflow] (media/screenshots/opencode-startup-menu.png) + +Development Kit provides one guided entry point, then selects the appropriate lifecycle action, command, agent, and skills. + +### Persistent lifecycle state + +! [Development Kit Autopilot showing the current lifecycle stage and next action] (media/screenshots/autopilot-lifecycle-status.png) + +The workflow progresses through `UNDERSTAND > DEFINE > DESIGN > PLAN > IMPLEMENT > VERIFY > REVIEW > SIMPLIFY > COMPLETE` and records state between sessions. + +### Human control for consequential actions + +! [Development Kit requesting explicit approval before a consequential operation] (media/screenshots/approval-gate.png) + +Remote, destructive, deployment, publishing, release, and security-sensitive actions stop for explicit authorization. + +### Validation evidence + +! [Development Kit release validation suite passing] (media/screenshots/release-validation.png) + +The release gate validates framework structure, plugin synchronization, documentation, OpenCode configuration, the Autopilot runtime, and behavioural evaluation scenarios. + +[ View the complete evidence walkthrough ] (marketing/product-showcase.md) +``` + +## Placement + +Insert the final section after `Current release` and before the detailed capability table. This gives visitors immediate product proof before they encounter the complete technical inventory. + +## Publishing rule + +Do not merge broken image references, placeholder URLs, fabricated screenshots, or a `coming soon` hero section into the public README. Keep this template on the marketing branch until every referenced asset is real and reviewed. diff --git a/marketing/recording-checklist.md b/marketing/recording-checklist.md new file mode 100644 index 0000000..08b4aca --- /dev/null +++ b/marketing/recording-checklist.md @@ -0,0 +1,45 @@ +# Recording and Privacy Checklist + +Complete this checklist before publishing any Development Kit screenshot or video. + +## Environment + +- [ ] The recording uses a dedicated public demo workspace. +- [ ] Development Kit and the host environment versions are known. +- [ ] The workspace contains no customer, employer, or confidential project data. +- [ ] Notifications are disabled. +- [ ] Browser bookmarks, account menus, avatars, unrelated tabs, and private repositories are hidden. +- [ ] Terminal history and environment variables have been reviewed. +- [ ] No password manager, API key, token, email address, phone number, or private URL appears on screen. +- [ ] File paths do not reveal unnecessary personal information. + +## Product accuracy + +- [ ] The demonstrated command exists in the current public release. +- [ ] The displayed output comes from real execution. +- [ ] The workflow follows the documented lifecycle. +- [ ] Approval gates are shown accurately and are not bypassed for presentation. +- [ ] Captions describe only what the visible evidence supports. +- [ ] Any accelerated or shortened sequence is disclosed. +- [ ] Version numbers are visible or stated in the description. + +## Visual quality + +- [ ] Text remains readable at normal playback size. +- [ ] The capture uses a consistent 16:9 frame. +- [ ] Cursor movement is controlled. +- [ ] Dead time and repeated typing are removed. +- [ ] Cropping does not hide a relevant warning or failed step. +- [ ] Screenshots use concise alt text. +- [ ] Videos include captions and a transcript. +- [ ] Audio levels are consistent and narration is intelligible. + +## Publication + +- [ ] Canonical filenames follow `media/README.md`. +- [ ] The source date and Development Kit version are recorded in the pull request. +- [ ] The full video URL is stable and publicly accessible. +- [ ] The README thumbnail opens the intended video. +- [ ] Repository and documentation links have been validated. +- [ ] `npm run release:validate` passes before merge. +- [ ] A second person or separate review pass has checked for privacy and accuracy issues. diff --git a/marketing/video-storyboard.md b/marketing/video-storyboard.md new file mode 100644 index 0000000..5d0baf7 --- /dev/null +++ b/marketing/video-storyboard.md @@ -0,0 +1,75 @@ +# Public Demo Video Storyboard + +## Primary video + +Target length: 75 to 90 seconds + +Target audience: developers, public users, technical evaluators, and potential partners + +Core message: Development Kit turns an AI coding agent into a disciplined, verifiable software-development workflow with persistent lifecycle state and explicit human control. + +## Storyboard + +| Time | Visual | Narration or caption | +|---|---|---| +| 0:00 to 0:07 | Fast montage of a vague request, a large unverified diff, and a failed check | AI coding is fast. Unstructured AI development creates rework, hidden assumptions, and unverified claims. | +| 0:07 to 0:15 | Terminal shows `npm view development-kit version`, then the OpenCode dry run | Development Kit installs a repeatable engineering workflow into OpenCode and Antigravity. | +| 0:15 to 0:24 | OpenCode opens the workspace and shows the recommended workflow entry | Start with one guided entry point. Development Kit chooses the correct lifecycle action, command, agent, and skills. | +| 0:24 to 0:39 | `/dk-autopilot` starts and shows `UNDERSTAND > DEFINE > DESIGN > PLAN` | Work moves through an explicit nine-stage lifecycle instead of jumping directly into code. | +| 0:39 to 0:52 | Status or state view shows current stage, action, and recorded progress | Progress is persistent, inspectable, and recoverable across sessions. | +| 0:52 to 1:04 | Approval gate appears before a remote or release action | Consequential operations stop for explicit human approval. Automation does not silently push, merge, deploy, publish, or accept security risk. | +| 1:04 to 1:17 | `npm run release:validate` summary passes | The framework, documentation, OpenCode configuration, Autopilot runtime, and behavioural evaluations are validated before release. | +| 1:17 to 1:27 | GitHub repository, npm package, and current release | Development Kit is public, open source, and installable from npm. | +| 1:27 to 1:30 | Product name, repository name, package, and call to action | Install Development Kit and build with discipline, evidence, and control. | + +## On-screen text + +Use short overlays only: + +- Nine-stage lifecycle +- 13 workflow commands +- 18 specialist agents +- 43 engineering skills +- Human approval gates +- Persistent workflow state +- Automated validation +- Open source and available on npm + +Do not show all metrics at once. Use one evidence-backed statement per scene. + +## Narration draft + +AI coding is fast. But without a disciplined workflow, speed creates rework, hidden assumptions, oversized changes, and unverified claims. + +Development Kit installs a repeatable software-engineering process into OpenCode and Antigravity. + +Start with one guided workflow. Development Kit inspects the repository, identifies the current lifecycle stage, and selects the correct command, specialist agent, and engineering skills. + +Work moves through nine explicit stages, from understanding and definition to implementation, verification, review, simplification, and completion. + +Progress is persistent and recoverable across sessions. When an action becomes consequential, Development Kit stops and asks for explicit human approval. + +Before release, the framework, documentation, OpenCode integration, Autopilot runtime, and behavioural evaluations are validated automatically. + +Development Kit is open source and available from npm. Build with discipline, evidence, and control. + +## Editing notes + +- Use real screen recordings for every product scene. +- Keep terminal commands visible long enough to read. +- Add subtitles for the full narration. +- Use gentle zooms rather than rapid camera movement. +- Remove typing mistakes and dead time without altering outcomes. +- Label accelerated sequences as `sped up` when the speed change is material. +- End with the repository name, npm package, and current version. + +## Short derivatives + +Cut the master recording into: + +1. A 15-second installation clip +2. A 25-second Autopilot lifecycle clip +3. A 20-second approval and safety clip +4. A 20-second validation and proof clip + +These clips can be used in the README, release notes, social posts, and investor outreach. diff --git a/media/README.md b/media/README.md new file mode 100644 index 0000000..97487a0 --- /dev/null +++ b/media/README.md @@ -0,0 +1,56 @@ +# Product Evidence Media + +This directory is the canonical home for public screenshots, animated demonstrations, video thumbnails, and social-preview assets for Development Kit. + +## Evidence standard + +All product evidence must show real Development Kit behaviour from a clean or clearly identified test workspace. + +Do not present mock interfaces, generated terminal output, staged validation results, or AI-generated UI as execution evidence. Illustrative graphics may be used for branding, but they must be labelled as illustrations rather than product screenshots. + +## Directory structure + +```text +media/ +├── screenshots/ # Static PNG or WebP product captures +├── demos/ # Short GIF or WebP demonstrations and local video source notes +├── social/ # Repository social-preview and campaign artwork +└── README.md +``` + +## Required launch assets + +| Asset | Purpose | Preferred format | +|---|---|---| +| `screenshots/opencode-startup-menu.png` | Proves the recommended workflow entry experience | PNG, 1600 x 900 | +| `screenshots/autopilot-lifecycle-status.png` | Shows persistent lifecycle state and the current action | PNG, 1600 x 900 | +| `screenshots/approval-gate.png` | Demonstrates human control over consequential operations | PNG, 1600 x 900 | +| `screenshots/release-validation.png` | Shows the complete verification suite passing | PNG, 1600 x 900 | +| `screenshots/npm-installation.png` | Demonstrates public installation from npm | PNG, 1600 x 900 | +| `demos/quick-install.webp` | Fast installation proof for the README | Animated WebP or GIF, under 8 MB | +| `demos/autopilot-overview.webp` | Short product workflow demonstration | Animated WebP or GIF, under 10 MB | +| `social/repository-preview.png` | GitHub and social sharing preview | PNG, 1280 x 640, under 1 MB | +| `social/product-demo-thumbnail.png` | Clickable thumbnail for the hosted full demo | PNG, 1280 x 720 | + +## Full video hosting + +Keep the source recording and edited master outside the npm package. Publish the final demonstration to a stable public host such as YouTube or Vimeo, then link to it from a repository thumbnail. + +A short MP4 may also be attached to a GitHub issue, pull request, discussion, or release for direct evidence and review. Browser codec support can vary, so the repository should retain a static thumbnail and written walkthrough as fallbacks. + +## Capture rules + +1. Use Development Kit v0.4.2 or later and show the version on screen. +2. Use a dedicated demo workspace with no customer data, secrets, personal paths, email addresses, tokens, or unrelated repositories. +3. Use a consistent 16:9 recording frame, ideally 1920 x 1080. +4. Increase terminal and editor font sizes so text remains readable on mobile. +5. Hide notifications, bookmarks, account avatars, unrelated tabs, and personal desktop content. +6. Keep cursor movement deliberate and remove dead time during editing. +7. Caption every public video and provide a short written transcript. +8. State clearly when a sequence is shortened, accelerated, or edited. +9. Preserve the original unedited recording privately for authenticity review. +10. Re-record evidence when a release materially changes the demonstrated behaviour. + +## File naming + +Use lowercase kebab-case names. Avoid dates in canonical filenames so README links remain stable across refreshes. Record the captured Development Kit version and source recording date in the pull request that adds or replaces each asset. diff --git a/media/demos/README.md b/media/demos/README.md new file mode 100644 index 0000000..daf7b89 --- /dev/null +++ b/media/demos/README.md @@ -0,0 +1,42 @@ +# Demo Media + +This directory contains short, repository-friendly demonstrations and notes that point to the hosted full product video. + +## Recommended public media set + +### Quick install + +A 10 to 15 second silent or captioned animation showing: + +1. `npm view development-kit version` +2. `npx development-kit@0.4.2 init --opencode --dry-run` +3. The generated file plan + +Target filename: `quick-install.webp` + +### Autopilot overview + +A 20 to 35 second animation showing: + +1. OpenCode loading the Development Kit workspace +2. The recommended automated workflow entry +3. `/dk-autopilot` selecting a lifecycle action +4. A visible pause at a human approval gate +5. `/dk-status` or equivalent state evidence + +Target filename: `autopilot-overview.webp` + +## Full video + +The full demonstration should be hosted externally and represented in the README with `../social/product-demo-thumbnail.png` linked to the public video URL. + +Do not commit large master video files to the npm package. Keep editable source footage outside the package and retain an archive copy under maintainer control. + +## Editing requirements + +- Add captions. +- Remove idle time and repeated typing. +- Use modest speed changes only when disclosed. +- Keep commands and outcomes readable. +- Avoid music that competes with narration. +- Include a closing frame with the repository name, npm package, and current version. diff --git a/media/screenshots/README.md b/media/screenshots/README.md new file mode 100644 index 0000000..f8030eb --- /dev/null +++ b/media/screenshots/README.md @@ -0,0 +1,35 @@ +# Screenshot Evidence + +Add only real product captures to this directory. + +## Capture set + +The first public evidence set should contain: + +1. `opencode-startup-menu.png` +2. `autopilot-lifecycle-status.png` +3. `approval-gate.png` +4. `release-validation.png` +5. `npm-installation.png` + +## Composition + +- Use a 16:9 crop with the relevant OpenCode or terminal area filling most of the frame. +- Keep the product state and command visible without exposing personal paths or account information. +- Crop unused desktop space. +- Use consistent editor theme, terminal font, zoom, and window dimensions across the set. +- Prefer PNG for terminal and editor text because it preserves sharp edges. +- Add short descriptive alt text wherever the image appears in Markdown. + +## Evidence notes + +For each screenshot pull request, state: + +- Development Kit version +- OpenCode version when relevant +- Operating system +- Exact command or interaction shown +- Whether any sensitive information was redacted +- Whether the image was cropped or annotated + +Annotations may identify controls or lifecycle stages, but must not alter the underlying output. diff --git a/media/social/README.md b/media/social/README.md new file mode 100644 index 0000000..bc7f851 --- /dev/null +++ b/media/social/README.md @@ -0,0 +1,36 @@ +# Social and Promotional Assets + +Use this directory for repository preview artwork, demo thumbnails, and campaign graphics. + +## Required assets + +### Repository preview + +Filename: `repository-preview.png` + +Recommended content: + +- Development Kit name +- One-line value proposition +- `UNDERSTAND > DEFINE > DESIGN > PLAN > IMPLEMENT > VERIFY > REVIEW > SIMPLIFY > COMPLETE` +- Antigravity and OpenCode support +- `development-kit@0.4.2` + +Use a 1280 x 640 PNG under 1 MB for the GitHub social-preview image. + +### Product demo thumbnail + +Filename: `product-demo-thumbnail.png` + +Recommended content: + +- Clear `Watch the 90-second demo` call to action +- A real, legible OpenCode or terminal screenshot as the background +- Development Kit branding +- A visible play icon + +Use a 1280 x 720 PNG. + +## Authenticity + +Promotional graphics may use layout, typography, and branding treatments. Any product interface shown inside them must come from a real capture. Do not create fictional UI states or fabricated terminal output.