Understand the Project Spec

The Project Spec is the structured definition of your product. It records goals, pages, features, rules, data, and flows in a form Castaly can keep using across conversations and builds.

Castaly maintains the Spec through Chat. You describe what you want, Castaly clarifies when needed, and the settled requirements are written into the Spec. When you press Build, Castaly builds from the Spec, not from your latest chat message.

Why the Spec matters

✅It records decisions

Product goals, constraints, rules, and accepted decisions live in one durable definition.

🧱It keeps Build aligned

Every Build reads from the Spec, so implementation follows the approved product definition.

🔎It gives you something to verify

You can check the exact requirements before Castaly turns them into code.

🧭It carries context forward

The Spec stays with the Project across conversations, previews, and future iterations.

Most day-to-day review can happen in the Graph. Open the Spec when exact wording, rules, or acceptance details matter.

What’s inside the Spec

The Spec is stored as a real Markdown file tree. Castaly maintains the files for you, so you do not need to write or organize them yourself.

📄Project goals and rules

Project goals, scope, global rules, core concepts, and key decisions.

🎨Design system rules

Global visual, layout, component, and accessibility rules.

📑Page-level requirements

Requirements for each page in the product.

🧩Feature requirements

Requirements for complex or cross-page capabilities.

🗂️Shared data meaning

Data concepts and meaning shared across pages and features.

🔀Cross-page flows

User tasks that span multiple pages, features, or steps.

At the bottom, a System group holds project-map.json, the map that powers the Graph. It stays collapsed by default; the Graph is its friendly, visual version.

How to read the Spec tab

The Spec tab is a read-only file explorer: the file tree on the left, rendered Markdown on the right.

• File tree on the left. Browse the actual Spec files and folders Castaly maintains.
• Rendered Markdown on the right. Read requirements in a formatted view instead of editing raw files.
• Search by file name. Open search from the file tree to filter files as you type. Markdown content search is not searchable yet.
• Status lives on the Graph. The Spec shows requirements, not build status or change markers.
• No editing here. There are no Edit, Copy, Download, or Export actions. Changes always start in Chat.

The Spec is read-only on purpose. Edits go through Chat so Castaly can preserve the structure and keep every Build tied to one coherent source of truth.

Ask Castaly about a Spec section

Want to question or change one part of the Spec? Select the text, heading, or paragraph you mean. A lightweight Ask Castaly action appears next to your selection and carries that file and location back to Chat as context.

1. 1

   Select text

   Highlight the text, heading, or paragraph you want Castaly to consider.

2. 2

   Use Ask Castaly

   The file path and selected snippet attach to your next message as context. Your input box is not overwritten, and nothing sends automatically.

3. 3

   Add your intent and send

   Say what you want changed, questioned, or clarified, then press Send. Castaly handles it through Chat like any other Project request.

The Spec is the source every Build reads from, but selecting a section does not start a Build. See Start a Build for how the Spec becomes implementation.

Next: Read the Project Graph shows the same Project structure visually.