Metadata-Version: 2.4
Name: aprovan-cicadas
Version: 0.6.3
Summary: Sustainable, Spec-Driven Development (SDD) for human-AI teams
Project-URL: Homepage, https://github.com/ecodan/cicadas
Project-URL: Documentation, https://github.com/ecodan/cicadas#readme
Project-URL: Repository, https://github.com/ecodan/cicadas.git
Project-URL: Issues, https://github.com/ecodan/cicadas/issues
Project-URL: Changelog, https://github.com/ecodan/cicadas/releases
Author: Cicadas Contributors
Maintainer: Cicadas Contributors
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai-development,cli,development-workflow,documentation,methodology,sdd,spec-driven-development
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# 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:

```bash
pip install cicadas
```

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

```bash
cd your-project
cicadas init
```

#### Option 2: Install Script (with Agent Integration)

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

```bash
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:**

```bash
# 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
bash install.sh --dir tools/cicadas --agent claude-code
```

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

```bash
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:

```text
.
├── 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](docs/cicadas-method-general.md)**

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

📘 **[SDD Comparison](docs/sdd-comparison.md)**

---

## License

Cicadas is licensed under the [Apache License 2.0](LICENSE).
Copyright 2026 Cicadas Contributors

This product includes software developed by Dan and contributors.

---

_Copyright 2026 Cicadas Contributors_
_SPDX-License-Identifier: Apache-2.0_
