mirror of
https://github.com/selfxyz/self.git
synced 2026-04-27 03:01:15 -04:00
408e2fa4de
* save wip * finalize pr * pr feedback * update specs. feedback * add handoff security doc
Self SDK — Spec System
Table of contents for the spec folder. Start here.
What This Is
A three-tier spec system designed for parallel AI agent execution:
- Project Overview — architecture, contracts, cross-workstream dependencies
- Workstream Overviews — orientation for each person/scope (what you own, context, status)
- Implementation Specs — exact code changes, I/O examples, token-budgeted chunks
Specs double as AI agent prompts. Written in second person, sized for single context windows, with validation commands after every chunk.
Meta-Framework
| File | Purpose | When to Read |
|---|---|---|
| SPEC-GUIDE.md | How to write specs (generic, portable to any project) | Before writing or reviewing any spec |
| TEMPLATES.md | Copy-paste templates for all three tiers | When creating a new spec |
| PROJECT-RULES.md | Project-specific rules and guardrails | Before starting any implementation work |
Project-Level Specs
| File | Purpose | When to Read |
|---|---|---|
| SDK-OVERVIEW.md | Architecture, bridge protocol, module table, decision matrix, glossary | First. Always. |
| WAVE-PLAN.md | Dependency-ordered execution plan for parallel agent work | When planning which chunks to execute next |
Workstream Specs
Each workstream has two files: OVERVIEW.md (stable orientation) and SPEC.md (living implementation details).
| Workstream | Overview | Implementation Spec | Status |
|---|---|---|---|
| Person 1 — WebView UI + Bridge | OVERVIEW | SPEC | 28/29 done, 1 pending (dynamic proving config) |
| Person 2 — Native Shells (KMP + Swift) | OVERVIEW | SPEC | 27/28 done, 1 pending (KMP test app validation) |
| Person 3 — Integrations | OVERVIEW | MiniPay Spec | 25/26 done, 1 pending (physical-device NFC E2E) |
| Person 4 — SDK Core | OVERVIEW | SPEC | 23/25 done, 2 pending (adapter dedup, crypto) |
| Person 5 — RN SDK | OVERVIEW | SPEC | 21/23 done, 2 pending (wallet integration, npm) |
Reading Order
New to the project?
- This README
- SDK-OVERVIEW.md — understand the architecture
- Your workstream's
OVERVIEW.md— understand what you own - Your workstream's
SPEC.md— understand what to build
Starting a work session?
- WAVE-PLAN.md — find the next available chunk
- Your workstream's
SPEC.md— read the chunk, check status - PROJECT-RULES.md — refresh on guardrails
Writing a new spec?
- SPEC-GUIDE.md — how to write specs
- TEMPLATES.md — copy-paste the right template
- PROJECT-RULES.md — project-specific constraints