Documentation Stack — clew
Bundle OKF 0.1 · 0 conceitos · VictorHueni/clew
Open source Repository Open in the app JSON README (API)
About
# Documentation Stack — clew
> **Scaffolded:** 2026-07-24 · **Last refreshed:** 2026-07-24
>
> Run the Scaffold mode Mode 3 to refresh status.
> Run the Audit mode Mode 2 for a full progress snapshot.
>
> This is the OKF bundle root `index.md` (reserved file — no artefact frontmatter).
---
## Stack progress
Status key: ✅ Done · 🔄 In progress (scaffold exists, needs filling) · ⬜ Not started
| Step | Artefact | Skill | Status | Canonical path | Last modified |
|---|---|---|---|---|---|
| 0 | Product Vision | `business-vision` | ✅ | [`docs/VISION.md`](VISION.md) | 2026-07-22 |
| 1 | Personas | `business-persona` | ✅ | [`docs/business/01a-personas.md`](business/01a-personas.md) | 2026-05-26 |
| 2 | Business Model Canvas | `business-model-canvas` | ✅ | [`docs/business/02a-lean-canvas.md`](business/02a-lean-canvas.md) (Lean Canvas variant) | 2026-07-24 |
| 2b | Bounded Context Map | `domain-bounded-context` | ✅ | [`docs/domain/02b-bounded-contexts.md`](domain/02b-bounded-contexts.md) |
Details
- Kind
- OKF bundles
- Topic
- Developer tools
- Publisher
- victorhueni
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Last push
- 2026-08-13T04:26:39Z
- Repository state
- ativo
- Added
- 2026-09-09 12:07:44
- Updated
- 2026-09-09 12:07:44
- Origin id
VictorHueni/clew:docs/index.md
README
# clew
> *A clew is the corner of a sail you pull to steer, and the thread that guides you through the labyrinth.*
**clew** is an AI-native product intelligence CLI. It is the structured knowledge layer that AI agents (Claude, Codex, and others) use to build, persist, and query the full architecture of a product, from business personas to domain models to delivery epics.
---
## What it does
```bash
clew init # configure clew for a repo
clew new persona "OR Coordinator" # → P-01
clew new capability "Schedule Management" # → C-3
clew new functionality "Generate schedule" --cap C-3 # → C-3.1.F01
clew set complexity C-3.1.F01 L
clew new epic "Scheduling core" # → E-01
clew link C-3.1.F01 E-01
clew estimate epic E-01 # → { best: 8d, likely: 12d, worst: 18d }
clew export yaml # → snapshot/ for git readability
```
Agents call clew via Bash. IDs are generated by the DB, never by the LLM. Markdown narrative written by the agent references the IDs returned by clew.
---
## The metamodel
clew manages a complete **strategic-architecture documentation system** across five layers. Skills from [homemade-claude-kit](https://github.com/VictorHueni/homemade-claude-kit) produce the markdown narrative; clew persists the structured records and relationships.
### Artefact layers and build order
19 artefacts grouped into packages by kit prefix — cross-cutting **Discovery**, **Business Architecture** (Step 0 vision through Step 6, plus competitive landscape), **Domain**, **Product Specs** (Steps 7 · 9 · 9.5 · 10), **Planning** (Steps 8 · 11 — delivery roadmap + implementation plans, split out of `spec-` per [ADR-0009](docs/architecture/decisions/adr-0009-plan-package-split-from-product-specs.md)), and **Architecture** (ADR + service/CLI contracts). This is the build-order view; **Operations** stays out of it entirely (post-ship, mints no IDs, no numbered step) — full reference in [`docs/metamodel/`](docs/metamodel/). **Quality Assurance** is shown too, off to the side: it isn't a numbered build-order step either (it's the post-ship validate/test layer), but its `test_strategy` artefact is active, so it's drawn here for completeness rather than staying doc-only. Solid arrows = hard dependency; dashed arrows = supporting enrichment. Each edge is named with its relationship: `UPPERCASE` is the canonical typed relationship clew stores in `artefact_references.relationship` and validates against the `ALLOWED_RELATIONSHIPS` registry (see the [domain model §Relationship registry](docs/domain/07b-models/artefact-store.md#relationship-registry)); lowercase names are softer/advisory links the registry does not type, or read in the build-order (prerequisite→dependent) direction.
```mermaid
flowchart TD
classDef business fill:#FEF3C7,stroke:#D97706,color:#92400E
classDef discovery fill:#CCFBF1,stroke:#0D9488,color:#115E59
classDef domain fill:#EDE9FE,stroke:#7C3AED,color:#4C1D95
classDef specs fill:#DBEAFE,stroke:#3B82F6,color:#1E40AF
classDef delivery fill:#D1FAE5,stroke:#10B981,color:#065F46
classDef arch fill:#FEE2E2,stroke:#EF4444,color:#7F1D1D
classDef qa fill:#FEF9C3,stroke:#CA8A04,color:#854D0E
classDef qaPlanned fill:#FEF9C3,stroke:#CA8A04,color:#854D0E,stroke-dasharray:4 3
subgraph DISC["Discovery — cross-cutting · pre-formal evidence"]
IDX["discovery-idea · IDEA-NNNN"]:::discovery
RES["discovery-research"]:::discovery
WS["discovery-workshop"]:::discovery
end
subgraph BA["Business Architecture: Step 0 · Steps 1–6 + 4.5"]
S0["0 · business-vision · VISION.md · north star"]:::business
S1["1 · business-persona · P-NN"]:::business
S2["2 · business-model-canvas"]:::business
S3["3 · business-capability-map · C-N.M"]:::business
S4["4 · business-value-stream · VS-N.M"]:::business
S4b["4.5 · business-objective · OBJ-NN · KR-NN.M"]:::business
S5["5 · business-process"]:::business
S6["6 · business-quantitative-model"]:::business
CL["business-competitive-landscape · CO-NN"]:::business
end
subgraph DOM["Domain Layer: Steps 2b · 2c · 7b"]
S2b["2b · domain-bounded-context · BC-NN"]:::domain
S2c["2c · domain-glossary · BC-NN.GT-NN"]:::domain
S7b["7b · domain-model · BC-NN.AGG / ENT / VO / EVT"]:::domain
end
subgraph PS["Product Specs: Steps 7 · 9 · 9.5 · 10"]
S7["7 · spec-functional-breakdown-structure · C-N.M.FXX"]:::specs
S9["9 · spec-quality-attributes · QA-XXNN"]:::specs
S9_5["9.5 · spec-use-case · UC-NN"]:::specs
S10["10 · spec-prd · PRD-NNNN"]:::specs
end
subgraph PLAN["Planning: Steps 8 · 11"]
S8["8 · plan-delivery-roadmap · E-NN"]:::delivery
S11["11 · plan-implementation · Plan-NNNN"]:::delivery
end
subgraph ARCH["Architecture: ADR + Contracts (Steps 7c · 8.5)"]
ADR["arch-adr · ADR-NNNN"]:::arch
S7c["7c · arch-service-contract · BC-NN.CTR-NN"]:::arch
S8_5["8.5 · arch-cli-contract · CLI-NN.CMD-NN"]:::arch
end
subgraph QA["Quality Assurance: post-ship, not a numbered step"]
TS["qa-test-strategy · TS-NN"]:::qa
TSC["test-scenario (planned)"]:::qaPlanned
TC["test-case (planned)"]:::qaPlanned
TP["test-plan (planned)"]:::qaPlanned
end
S0 -.->|"scopes audience"| S1
S0 -.->|"frames VP"| S2
S0 -.->|"sets intent"| S4b
S0 -.->|"guides"| S8
S1 -->|"SEGMENTS"| S2
S1 -->|"informs"| S3
S1 -->|"TRIGGERS"| S4
S3 -->|"consumed by"| S4
S4 -->|"operationalised by"| S5
S2 -->|"quantified by"| S6
S1 -.->|"serves outcomes"| S4b
S2 -.->|"VP intent"| S4b
S4 -->|"pain informs"| S4b
S4b -.->|"epics serve"| S8
S4b -.->|"KR grounds"| S9
S4b -.->|"traces to"| S10
S3 -->|"GROUPS_INTO"| S2b
S4 -->|"SIGNALS"| S2b
S2b -->|"SCOPES"| S2c
S2b -->|"MODELS"| S7b
S3 -->|"inherited by"| S7
S7 -->|"BECOMES"| S7b
S2c -->|"names terms"| S7b
S7b -->|"EXPOSES"| S7c
S7 -->|"grouped into"| S8
S7 -->|"surfaced by"| S8_5
S8 -->|"phases commands"| S8_5
S7b -->|"referenced by"| S10
S8 -->|"scopes QA"| S9
S8_5 -.->|"per-command SLA"| S9
S8_5 -.->|"referenced by"| S10
S7c -.->|"referenced by"| S10
S9 -->|"CONSTRAINS"| S10
S1 -.->|"ACTOR_OF"| S9_5
S7 -.->|"realised by"| S9_5
S9_5 -->|"GROUNDS"| S10
S10 -->|"DETAILS"| S11
ADR -.->|"GOVERNS"| S7c
ADR -.->|"DECIDES"| S8_5
ADR -.->|"DECIDES"| S9
ADR -.->|"DECIDES"| S10
CL -.->|"TARGETS"| S1
CL -.->|"POSITIONS"| S2
RES -.->|"validates"| S1
RES -.->|"validates"| S2
RES -.->|"validates"| S6
WS -.->|"aligns"| S2
WS -.->|"aligns"| S4
IDX -.->|"graduates to"| S0
S9 -.->|"defines tests for"| TS
TS -.->|"scopes"| TP
TP -.->|"scopes"| TSC
S9_5 -.->|"realises"| TSC
TSC -.->|"expands into"| TC
S10 -.->|"is oracle for"| TC
S11 -.->|"verified by"| TP
```
---
## Architecture
clew has three layers:
```
AGENT (Claude / Codex)
calls clew via Bash → gets deterministic IDs back
writes markdown prose referencing those IDs
CLEW CLI (Typer + SQLite)
CRUD commands per entity type
ID generation via DB sequences, never by the LLM
FK enforcement at write time
YAML export → snapshot/ for git readability
MARIMO NOTEBOOKS (read-only analysis)
Effort estimates + rollup to epics
Roadmap / Gantt
KR coverage, financial models
```
Upgrade path: CLI → MCP server → HTTP API, all wrapping the same core layer. See [`docs/architecture/decisions/`](docs/architecture/decisions/) for the full rationale.
---
## Where to start reading
This repository is its own first project. The artefacts in [`docs/business/`](docs/business/) document clew using clew's own intended methodology, as a worked example for anyone evaluating the approach.
Depending on what you came for:
- **What is clew for?** → [`VISION.md`](docs/VISION.md) + [`docs/business/02a-lean-canvas.md`](docs/business/02a-lean-canvas.md)
- **Who is it built for?** → [`docs/business/01a-personas.md`](docs/business/01a-personas.md) (P-01 Ava, the agent-first product engineer)
- **What can it do? (capabilities)** → [`docs/business/03a-capability-map.md`](docs/business/03a-capability-map.md) (5 L0 domains, 19 L1 capabilities)
- **How does value flow?** → [`docs/business/04a-value-streams.md`](docs/business/04a-value-streams.md) (4 streams, fully decomposed, all triggered by P-01)
- **What are the goals and measures?** → [`docs/business/04b-objectives.md`](docs/business/04b-objectives.md) (3 OKRs, 12 KRs)
- **Why these technical decisions?** → [`docs/architecture/decisions/`](docs/architecture/decisions/) (ADRs ahead of implementation)
- **What does the user research say?** → [`docs/discovery/interviews/`](docs/discovery/interviews/) (wave-1 interview + synthesis, N=1, founder-as-instance)
Every artefact uses **stable IDs** (P-NN, C-N.M, VS-N.M, OBJ-NN, KR-NN.M, ADR-NNNN) and **soft-links** to related artefacts; clicking any ID-tagged link drills into the referenced artefact. Confidence is labelled throughout. Pain ratings and KR targets are anchored on wave-1 N=1 evidence; see the **Confidence-cliff watchpoint** in [`docs/business/04b-objectives.md`](docs/business/04b-objectives.md#obj-03--validate-the-core-hypotheses-before-scaling) for when this evidence base will be refreshed.
---
## Status
Early design phase. Business-layer modelling **complete** (personas, lean canvas, capability map, value streams, objectives, all wired bidirectionally; see §Where to start reading above). Spec + domain layers drafted (FBS, bounded contexts, the Artefact Store domain model, and the CLI interface contract). Architecture layer: **seven ADRs ahead of implementation** in [`docs/architecture/decisions/`](docs/architecture/decisions/) — persistence layer, file binding, schema design, implementation stack, frontmatter policy, type-definition home, and migration framework. **No CLI yet:** the commands shown in §What it does are the target shape, not the current state. Next: implement the `clew` package (ADR-0001/0003/0004/0007).
## License
MIT