cast-a-start

cast-a-start is a CAST Docs skill for turning an early project idea or an existing repository into a structured planning workspace before implementation begins.

It helps an agent and a human move from idea discussion to product plan, technical spec, TODOs, changelist, and coding readiness. The skill is intentionally a planning gate: if the required planning artifacts are missing, stale, or contradicted by open questions, it pauses implementation and fixes the project memory first.

Install

Install or update the cast-a-start Codex skill with GitHub CLI:

gh skill install CAST-docs/cast-a-start cast-a-start --pin v0.2.0 --agent codex --scope user

Install sibling cast-a-doc as well so cast-a-start can generate validated bilingual HTML planning documents:

gh skill install CAST-docs/cast-a-doc cast-a-doc --pin v0.2.0 --agent codex --scope user

The compatibility installer runs the same gh skill install flow and installs both skills by default:

curl -fsSL https://cast-docs.github.io/cast-a-start/install.sh | bash

To install only cast-a-start, pass --skip-cast-a-doc.

Install cast-a-start for Claude Code:

gh skill install CAST-docs/cast-a-start cast-a-start --pin v0.2.0 --agent claude-code --scope user
gh skill install CAST-docs/cast-a-doc cast-a-doc --pin v0.2.0 --agent claude-code --scope user

Install cast-a-start for both agents:

curl -fsSL https://cast-docs.github.io/cast-a-start/install.sh | bash -s -- --both

See RELEASE.md for the relationship between main, the v0.2.0 install pin, the compatibility installer defaults, and the cast-a-doc renderer pin used by CI.

What It Provides

• A compact agent workflow in skills/cast-a-start/SKILL.md.
• A GitHub Pages entrypoint in index.html.
• Product planning documents under plan/.
• Technical design documents under spec/.
• A JSON-backed planning backlog rendered as TODO, written as a priority table rather than a status narrative.
• A JSON-backed change history rendered as CHANGELIST.
• GitHub CLI installation commands for Codex and Claude Code, plus a compatibility installer that also prepares cast-a-doc.
• A release policy in RELEASE.md and release.html.
• Examples under examples/ for new project starts and existing repository Rewrite Mode.
• A Rewrite Mode for adopting or reshaping existing repository documents with explicit user approval, document-by-document synthesis, JSON-first authoring, and renderer-validated diagrams.
• Guidance for using .cast-docs/project.json as a project profile layer, including standardized styleProfile settings for branded CAST Docs output.

When To Use

Use cast-a-start when a user wants to start a project from an idea, prepare implementation context, migrate existing repository documents, repair stale project memory, or coordinate README, plan, spec, TODO, CHANGELIST, and rendered Pages artifacts before coding.

Do not load it for every small code edit. If the task already has fresh project memory, a passing selected gate, and no product, architecture, release, or documentation contract change, continue with the implementation workflow already in place.

Tool Model

cast-a-start is one skill with smaller conceptual tools for intake, inventory, rewrite planning, product plan, technical spec, progress, TODO, CHANGELIST, rendering, and gate checks. The public skill keeps the short operating contract in SKILL.md; the full repository-maintenance contract is documented in Tool Contracts.

Core Workflow

1. Intake the product idea and identify users, value, boundaries, constraints, risks, and success criteria.
2. If the repository already has documents, inventory them and ask the user to choose rewrite scope before overwriting anything.
3. For approved rewrites, read the selected source material and rewrite one target document at a time; scripts may assist inventory, validation, rendering, and formatting, but they are not a bulk document conversion shortcut.
4. Create or update JSON-backed project documentation sources, then render HTML through cast-a-doc.
5. Write product plan documents that explain the product, not the implementation.
6. Write technical spec documents that explain architecture, boundaries, data flow, verification, and rollout.
7. Record unresolved items in site/todo.json and regenerate todo.html.
8. Record meaningful changes in site/changelist.json and regenerate changelist.html.
9. Audit consistency whenever requirements change.
10. Enter implementation only after the selected coding gate passes.

Coding Gate

cast-a-start uses three coding gate levels so small projects do not inherit the full public-documentation burden.

• light: for small tools, spikes, and early ideas. Requires a current README or project brief, captured constraints/non-goals/open questions, and no unresolved question that changes the immediate implementation direction.
• standard: the default for continuing projects. Requires current plan/spec, TODO, CHANGELIST, propagated requirement changes, and traceability from the current implementation task to project memory.
• strict: for public releases, GitHub Pages docs, repository migrations, and cross-agent handoff. Requires the standard gate plus a reader-facing index.html, rendered TODO/CHANGELIST, fresh HTML artifacts for published JSON sources, no raw or static-image diagram surfaces in rendered HTML, and explicit user confirmation.

If the selected gate is missing or stale, cast-a-start fixes the planning workspace first. HTML rendering may be recorded as blocked only for source-only local work; strict release or migration work must pass freshness validation. Raw Mermaid, PlantUML, Graphviz, DOT, or flowchart text is not acceptable rendered diagram output; diagrams must come from supported diagram JSON or sanitized inline SVG.

For GitHub Pages work, the homepage should explain the project and route readers to readable README, plan, spec, TODO, and CHANGELIST pages. Internal JSON, manifest, profile, and style sources can remain available for maintainers, but they should not be primary homepage cards.

Relationship To cast-a-doc

cast-a-start is a sibling skill to cast-a-doc, not a subfeature. It uses cast-a-doc output conventions for bilingual static HTML planning artifacts, while focusing on project startup workflow and coding readiness.

If cast-a-doc is unavailable at runtime, cast-a-start should offer to install it, accept a renderer path, or continue in source-only mode with HTML rendering marked as blocked.

Regenerate Pages

The checked-in HTML files are rendered from JSON sources through the renderer-tool, which delegates to the sibling cast-a-doc JSON-to-HTML renderer and validation workflow. Do not hand-edit generated HTML. The local helper looks for the renderer in this order:

1. an explicit --renderer-root
2. CAST_A_DOC_ROOT
3. an adjacent checkout at ../cast-a-doc
4. installed sibling skills such as $CODEX_HOME/skills/cast-a-doc or $CLAUDE_HOME/skills/cast-a-doc

Check renderer availability:

python3 scripts/check_renderer.py

Run lightweight structural checks for the selected gate and document-tool wiring:

python3 scripts/gate_check.py --level strict
python3 scripts/doc_tool_check.py
python3 scripts/validate_skill_bundle.py

Regenerate all root, plan/, and spec/ HTML artifacts:

python3 scripts/render_all.py --validate

Verify checked-in HTML is fresh without rewriting files:

python3 scripts/render_all.py --validate --check

CI runs the same freshness check after checking out CAST-docs/cast-a-doc at the pinned renderer ref. Source-only fallback is for local planning sessions only and must not make CI pass.

If the renderer is unavailable during local planning work, record a source-only blocked report instead of promising HTML output:

python3 scripts/render_all.py --source-only --report .cast-docs/render-report.md

License

cast-a-start is licensed under the Apache License 2.0, except as noted in NOTICE.

The CAST Docs name, logo, and other project branding assets are not licensed for use in modified versions, derived products, or services without prior written permission. Truthful references to CAST Docs for origin or compatibility are allowed.