Cicadas

Version 1.0.0

Sustainable, Spec-Driven Development (SDD) for human-AI teams.

Cicadas reverses the traditional relationship between code and documentation. Instead of fighting to keep specifications in sync with code, Cicadas treats forward-looking docs (PRDs, plans) as disposable inputs that drive implementation and then expire. Authoritative system documentation is then reverse-engineered from the code itself into canonical snapshots.

---

The Core Concept

1. Active Specs are Disposable: PRDs, designs, and task lists drive implementation but expire when the initiative completes.
2. Code is Truth: The codebase is the only source of truth.
3. Work is Coordinated: Parallel initiatives and features are registered in a registry, allowing parallel work efforts to minimize overlap and clashes.
4. Canon is Synthesized: Authoritative documentation (canon/) is generated from the code + the intent of expired specs. It is never manually maintained, and larger repos use a more selective canon structure than smaller ones.
5. Reflect & Signal: During development, we keep specs honest via Reflect (updating active specs to match code reality) and coordinate via Signal (broadcasting breaking changes to peer branches).

---

Getting Started

Installation

One-liner (requires Python 3.11+ and git):

curl -fsSL https://raw.githubusercontent.com/ecodan/cicadas/master/install.sh | bash

This downloads Cicadas into .cicadas-skill/cicadas/, initializes the .cicadas/ workspace, and optionally sets up agent integrations. Re-running initialization is idempotent: existing registry, index, config, and active state are preserved.

With agent integration:

# Claude Code
curl -fsSL https://raw.githubusercontent.com/ecodan/cicadas/master/install.sh | bash -s -- --agent claude-code

# Codex
curl -fsSL https://raw.githubusercontent.com/ecodan/cicadas/master/install.sh | bash -s -- --agent codex

# Cursor
curl -fsSL https://raw.githubusercontent.com/ecodan/cicadas/master/install.sh | bash -s -- --agent cursor

# Rovodev
curl -fsSL https://raw.githubusercontent.com/ecodan/cicadas/master/install.sh | bash -s -- --agent rovodev

# Multiple agents
curl -fsSL https://raw.githubusercontent.com/ecodan/cicadas/master/install.sh | bash -s -- --agent claude-code,codex

Custom install directory:

bash install.sh --dir tools/cicadas --agent claude-code

Update Cicadas files (preserves your .cicadas/ workspace):

bash install.sh --update

• or -

curl -fsSL https://raw.githubusercontent.com/ecodan/cicadas/master/install.sh | bash -s -- --update

Supported agents: