layered-spec

Compact implementation spec syntax which makes AI code generation predictable for well-decomposed tasks and speeds up development.

General idea

Solution logic can be fully described in several layers, starting with a workflow diagram and then adding details gradually.

AI-agent generates high quality specs from task in chat. First 1-3 layers are for review by a user, remaining layers are for reliable code generation by AI.

Compact layered syntax makes spec driven development concise, fast, and convenient.

New! Requirements and Invariants layers are added into layered-spec.

Requirements

Layered-spec now supports explicit requirements. For complex products, requirements provide a clear source of truth for the behavior that must be implemented and make development easier to manage as the product evolves.

The new Requirements layer records normative behavior separately from implementation details. Declarative use cases provide a higher level of abstraction: they can define requirements without prescribing an implementation, then map those requirements to one or more realizing use cases when implementation details are needed.

Invariants

The new Invariants layer describes properties that must hold at selected workflow states and shows how transition logic derives each outcome invariant from earlier invariants.

Invariant definitions and derivations may use natural language, mathematical notation, pseudocode, Lean, or another named formalism. When formal verification is useful, an AI agent can generate the derivation in Lean and run a proof checker, making it possible to verify the corresponding specification logic.

Quick start

1. Install spec skills

Ask your AI-agent

Install skills from https://github.com/vieteio/layered-spec

npm install -g @viete-io/layered-spec@latest
cd your-project
layered-spec init

2. Describe task in a chat and add "Make spec for that" or "Update spec for that"

3. Review spec and edit it in the chat with AI

4. When spec is ready, write "Implement the spec" or "Implement spec update"

Spec-driven vibecoding

Skip spec review step.

Limit your work to

1. Describe task and add "Make spec for that"
2. Message in the chat "Implement the spec"

AI agent will decompose moderately level complexity tasks well into use cases with detailed workflow chains and then will generate code properly for well-decomposed tasks.

Skills

This repository contains a layered-spec skillpack for planning new features or refactoring through chat with an AI agent.

Canonical skill sources live under:

• skill/ — skill definitions
• planning/planning_contract.md — spec structure description

Spec lifecycle files live under:

• specs/spec-lifecycle/workflow.md — repository lifecycle workflow that users can review and customize
• specs/spec-lifecycle/workflow.json — workflow settings; validation preferences live in its validation section

Describe a task in chat with an AI agent and ask it to create a spec. Review the spec and refine it in chat. When the spec is correct, ask the agent to implement it in a loop.

Install skills for your IDE or agent

npm

npm install -g @viete-io/layered-spec@latest
cd your-project
layered-spec init

Requires Node.js 20.19.0 or later.

Select a release version

The default install always uses the newest stable release (latest):

npm install -g @viete-io/layered-spec
# equivalent: npm install -g @viete-io/layered-spec@latest

Use next to try the newest prerelease, or use an exact version to keep an installation reproducible:

npm install -g @viete-io/layered-spec@next
npm install -g @viete-io/[email protected]

To return to the stable release, install @latest again. The selected package version is recorded in .agents/layered-spec-skillpack.json (or the selected host's equivalent manifest) when you run layered-spec init.

Python installer

Clone this repository, then run the existing Python installer from its root:

python scripts/install_skillpack.py --host <host_name>

Requires Python 3.10 or later.

Installer options

init installs all supported hosts by default: vscode, cursor, claude, codex, and antigravity. Use --host <host_name> to install only one host.

Repo-scoped installs place skills under each host's expected directory (for example .github/skills/ for VS Code / GitHub Copilot, .cursor/skills/ for Cursor). The installer rewrites internal path references to match the selected host while keeping generated specs in specs/.

Demo project

See the layered-spec meetup demo project with spec and AI-agent chat log in the repo.

Interactive planning approach

Describe the app or new feature in a free-form way to give the AI agent a general understanding. This can also be a code refactoring task rather than a feature. The workflow syntax supports that, see the syntax below.

Then prepare workflows for each meaningful use case, each of which may start with some trigger such as user input or an API call.

Ask the AI agent to add workflows for any missing use cases.

Next, add layers to some workflows, fill those layers with examples, and ask the AI agent to complete the corresponding layers in other workflows.

Use typed workflows to control data flow strictly.

Recommended layers:

• Workflow
• Requirements and realization mappings
• Invariants
• Types and tables
• Logic
• Events and endpoints
• Detailed typed workflow
• Tests

Layered syntax

Workflow syntax

step: state 1 --step name--> state 2
conditional branches: [branch1, branch2, branch3]
parallel branches: (branch1, branch2, branch3)
workflow refactoring: {workflow1} --refactoring step--> {workflow2}
workflow loop: | loop condition: input --step name--> outcome |
inline comment: // comment
inline comment: # comment

Place loop workflows in fenced text blocks or inline code so the enclosing | characters are not interpreted as a Markdown table.

Example:

state 1 --step name 1--> state 2 --step name 2--> [
  conditional state 1 --branch 1 step--> branch 1 state, // first state option
  conditional state 2 --branch 2 step--> branch 2 state  // second state option
] --step name 3--> final state

| process each file: file --perform analysis--> report |

| while unfinished work items remain:
  current work state --select next item--> selected item # one item per iteration
  --process item--> updated work state |

Layered use cases

## Use cases

### 1. Use case name
workflow

Layer_1_name:
layer content

Layer_2_name:
multi line
layer content

Type or table layer syntax

Type description syntax:

Type_name
 - field_name1: optional_type # optional comment; for a table, the field name is a column
 - field_name2: optional_type
   - nested_field_name: optional_type # nested fields are not relevant for tables

Typed detailed workflow layer syntax

After type layers are defined, typed syntax can be used for the detailed workflow.

Syntax:

step: state 1: Type --step name--> state 2: Type

Example:

state 1: Tuple[A, B] --step name 1--> state 2: List[X] --step name 2--> [
  conditional state 1 --branch 1 step--> branch 1 state,
  conditional state 2 --branch 2 step--> branch 2 state
] --step name 3--> final state

Contributing

Contributions are welcome. To get started:

• Discuss first — join the Discord or open a GitHub issue to describe your idea before submitting a pull request.
• Syntax changes — include a concrete before/after example and confirm that existing README examples remain valid.
• Skill changes — describe the purpose of new or existing skill update, share your personal experience of how the skill worked for you to confirm it functions as intended.
• Docs and fixes — open a pull request directly against main with a short description of what changed and why.
• Bug reports — open a GitHub issue with a minimal layered-spec example, the expected behavior, and the actual behavior.

License

Released under the MIT License — free for commercial and non-commercial use.