105 lines
No EOL
5.3 KiB
Markdown
105 lines
No EOL
5.3 KiB
Markdown
# 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.
|
|
|
|
## The Chain of Custody for Intent
|
|
|
|
Agents generate code. Humans own specifications. The chain of custody for intent stays intact.
|
|
|
|
That's the old framing. Here's the better one:
|
|
|
|
**SpeckDL is the shared space that both humans and AI can work in.**
|
|
|
|
- **Human-judgeable** — SpeckDL is declarative enough that a person can inspect a spec and say "yes, this captures my intent." The compiled Wasm is opaque; the spec is not. That's the audit trail. Intent is encoded in the spec *because* it is verifiable by a person.
|
|
- **AI-writable** — SpeckDL's constrained grammar and declarative semantics make it tractable for LLMs to produce and reason about. Agents can draft, iterate, and refactor specs at machine speed — in the same language the human reviews.
|
|
|
|
The two properties together are symmetric: humans and agents collaborate in the same medium. The human provides direction and judgment. The agent provides speed and iteration. Both operate on the same semantic layer.
|
|
|
|
SpeckDL compiles directly to **Wasm** through a deterministic pipeline. The compiler isn't just a code generator — it's the enforcement point that guarantees what the human signed off on is what gets executed. If it compiles to valid Wasm, the binary is faithful to the spec by construction.
|
|
|
|
## 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 directly to Wasm:
|
|
|
|
|
|
|
|
No LLMs in the compilation path. No non-determinism. Same input, same output — every time.
|
|
|
|
## Architecture
|
|
|
|
|
|
|
|
- **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 |