Cicadas

Version 0.6.1

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.
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

Option 1: Install from PyPI (Recommended)

Install Cicadas as a Python package:

pip install cicadas

This installs the cicadas CLI command. Initialize Cicadas in your project:

cd your-project
cicadas init

Option 2: Install Script (with Agent Integration)

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. Lifecycle commands use the bundled CLI entry point python .cicadas-skill/cicadas/scripts/cli.py (same subcommands as the cicadas command from pip); optionally pip install cicadas to put cicadas on your PATH.

With agent integration:

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

# 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,cursor

Custom install directory:

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

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

bash install.sh --update

Supported agents:

Agent	Integration
claude-code	.claude/skills/cicadas symlink (uses project CLAUDE.md if present)
antigravity	.agents/skills/cicadas symlink
cursor	.cursor/rules/cicadas.mdc (copy of SKILL.md; guardrails are in the skill)
rovodev	.rovodev/skills/cicadas symlink
none	Skip; configure manually

Requirements: Python 3.11+, curl, unzip, git

---

The Workflow

Phase 1: Emergence (Drafting)

When you start an initiative, tweak, bug, or skill, the agent runs a standard start flow first (name → draft folder → Building on AI? (yes/no; if yes, eval status) → requirements source/pace for initiatives → publish destination for skills → PR preference), then drafts specs. For work that builds on AI, the agent may later offer an eval spec (initiatives) or an eval/benchmark reminder (tweaks/bugs); Cicadas does not run evals. We draft specifications in .cicadas/drafts/ using specialized instruction modules (Clarify, UX, Tech, Approach, Tasks, Skill Create). Clarify can be driven by Q&A, a requirements doc (drafts/{initiative}/requirements.md), or a Loom transcript (drafts/{initiative}/loom.md).

• Key Artifact: approach.md defines the partitions (feature branches).

Phase 2: Kickoff

We promote drafts to Active Specs and register the initiative.

• Command: cicadas kickoff {name} --intent "..." (or python {cicadas-dir}/scripts/cli.py kickoff … when using a copied skill tree)
• Result: Creates initiative/{name} branch and .cicadas/active/{name}/.

Phase 3: Execution (The Dual Loop)

Work happens in Feature Branches (registered) and Task Branches (ephemeral).

• Start Feature: cicadas branch {feature} --intent "..." --modules "…" --initiative {name}
• Reflect: When code implementation diverges from the plan, we update the active specs immediately (and before every commit on feat/task branches).
• Code Review (optional): After Reflect; before committing on feature branches; before opening a PR or merging. The agent evaluates the diff against specs, security, correctness, and quality — producing a structured review.md artifact with a PASS / PASS WITH NOTES / BLOCK verdict. cicadas open-pr checks this verdict and blocks on BLOCK.
• Signal: If a change affects other branches, we broadcast it: cicadas signal "..."

Phase 4: Completion (Synthesis)

When all features are merged into the initiative branch, we merge to main and then:

1. Synthesize Canon: An AI agent reads the code on main + the active specs and generates fresh documentation in .cicadas/canon/ (including canon/summary.md — a 300–500 token snapshot used to inject context at branch start).
2. Archive: Active specs are moved to .cicadas/archive/.

Quick command reference

Use the cicadas CLI (pip install cicadas) or, for a tree copied by install.sh, python {cicadas-dir}/scripts/cli.py with the same subcommands — one entry point instead of per-script paths.

Action	Command
Init	cicadas init
Kickoff Initiative	cicadas kickoff {name} --intent "..."
Start Feature	cicadas branch {name} --intent "..." --modules "…" --initiative {name}
Check Status	cicadas status (shows Merged/Next when lifecycle exists)
Check Conflicts	cicadas check
Send Signal	cicadas signal "Message..."
Log Work	cicadas update-index --branch {name} --summary "..."
Lifecycle	cicadas lifecycle {name} (PR boundaries + steps in drafts/active; use --no-pr-* / --pr-* as needed)
Open PR	cicadas open-pr [--base branch] (gh/glab/Bitbucket/fallback; blocks on BLOCK verdict)
Check Review	cicadas review [--initiative name] (read verdict from review.md)
Archive	cicadas archive {name} [--type branch|initiative]
Prune	cicadas prune {name} --type branch|initiative
Abort	cicadas abort
Project History	cicadas history [--output path]
Validate Skill	cicadas validate-skill {slug}
Publish Skill	cicadas publish-skill {slug} [--publish-dir DIR] [--symlink] [--force]
Refresh wiki nav	cicadas refresh-wiki

---

Project Structure

The Cicadas toolset manages the .cicadas/ directory:

.
├── src/
│   └── cicadas/                # The Cicadas orchestrator (scripts & agents)
└── .cicadas/
    ├── canon/                  # Authoritative, generated checks
    │   ├── product-overview.md
    │   ├── tech-overview.md
    │   └── modules/            # Module-level snapshots
    ├── active/                 # Live specs for in-flight initiatives
    ├── drafts/                 # Staging area for new initiatives
    ├── archive/                # Expired specs (historical record)
    └── registry.json           # Active initiatives & branch registry

Additional Resources

For the full methodology specification, see:

📘 Cicadas Method Specification

For a comparison of the Cicadas Method to other approaches, see:

📘 SDD Comparison

---

License

Cicadas is licensed under the Apache License 2.0. Copyright 2026 Cicadas Contributors

This product includes software developed by Dan and contributors.

---

Copyright 2026 Cicadas Contributors SPDX-License-Identifier: Apache-2.0