# Speckl

**Spec-first development with dark provenance.** Write what your system should do. Prove it. Ship with full traceability.

Speckl is a multi-agent software development system where the primary artifact is the *specification*, not the code. Every behavior traces back to its source of intent — automatically.

## Dark Provenance

Every function, every branch, every side effect in your system is linked to the specification that motivated it. The provenance graph accumulates behind the scenes — invisible until you need it, but always complete. When an auditor asks "why does this code exist?", you don't search Jira. You query the graph.

This isn't traditional traceability (forward-chaining from documents to code). It's the reverse: every runtime behavior backward-traces to its source specification. Specifications are small and stable. Code is derived. The audit surface stays tractable no matter how much code the system contains.

## SpeckDL

SpeckDL is the specification language at the core of Speckl. It defines *what* a system does, not *how*:

```
speck RetryHandler {
  input: { operation: Operation, maxRetries: Nat }
  output: Result
  constraint: maxRetries <= 5
  constraint: backoff(delay(n)) == delay(n-1) * 2
  constraint: totalDelay < 30s
  verify: always(implies(attempt > 1, delay > 0))
}
```

SpeckDL compiles through a deterministic pipeline:

![SpeckDL compilation pipeline](docs/diagrams/speckdl-pipeline.svg)

No LLMs in the compilation path. No non-determinism. Same input, same output — every time.

## Architecture

![Architecture diagram](docs/diagrams/architecture.svg)

- **Orchestrator** — client entry point, task decomposition
- **Team Leads** — manage specialized agents, elastic scaling
- **SMEs** — hyper-specialized single-task agents (verify, generate, document)
- **TillDone** — tasks complete when provable conditions are met, not when someone moves a card

Teams self-replicate under load. The harness scales dynamically without human intervention.

## Getting Started

1. **Read the whitepaper:** [docs/whitepapers/dark-provenance.md](docs/whitepapers/dark-provenance.md) — the core methodology
2. **Read the strategy:** [docs/strategy.md](docs/strategy.md) — how Speckl grows from standard → consulting → SaaS → compliance
3. **Explore the SpeckDL spec:** [speckdl/SPEC.md](speckdl/SPEC.md) — language definition and examples
4. **Run the reference agent:** [reference-agent/](reference-agent/) — working tiered agent implementation

```bash
# Clone the repo
git clone https://os.scoble.me/forgejo/sscoble/speckl
cd speckl

# Run the reference agent
cd reference-agent
npm install
npm run dev
```

## Roadmap

Speckl follows a phased strategy — the open standard fuels everything else:

| Phase | Focus | Timeline |
|-------|-------|----------|
| **A — Open Standard** | SpeckDL language, Dark Provenance methodology, reference implementations | Now → 3mo |
| **B — Consulting** | Hands-on engagements with regulated-industry teams, validating the methodology | Now → 3mo (funds A) |
| **C — Developer Tool (SaaS)** | Self-serve platform: spec editor, live Z3 verification, provenance graph browser | 3 → 9mo |
| **D — Compliance API** | Enterprise provenance engine: audit reports, traceability matrices, compliance packs | 9 → 18mo |

The standard comes first. Adoption creates the market. The products follow.

## Contributing

Speckl is open source under the [MIT license](LICENSE). We welcome contributions:

- **Language design** — refine SpeckDL syntax and semantics
- **Formal methods** — help verify the compilation pipeline
- **Compliance expertise** — validate the DO-178C, IEC 62304, ISO 26262 models
- **Agent development** — build and test the tiered agent harness
- **Documentation** — make dark provenance accessible to working developers

Open an issue or submit a pull request. See [speckdl/SPEC.md](speckdl/SPEC.md) for the language spec and [docs/](docs/) for strategy and methodology documents.

## License

MIT © Scott Scoble / Greybeard Holdings, LLC