{
  "markdown": "# clew\n\n> *A clew is the corner of a sail you pull to steer, and the thread that guides you through the labyrinth.*\n\n**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.\n\n---\n\n## What it does\n\n```bash\nclew init                                        # configure clew for a repo\nclew new persona \"OR Coordinator\"                # → P-01\nclew new capability \"Schedule Management\"        # → C-3\nclew new functionality \"Generate schedule\" --cap C-3  # → C-3.1.F01\nclew set complexity C-3.1.F01 L\nclew new epic \"Scheduling core\"                  # → E-01\nclew link C-3.1.F01 E-01\nclew estimate epic E-01                          # → { best: 8d, likely: 12d, worst: 18d }\nclew export yaml                                 # → snapshot/ for git readability\n```\n\nAgents 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.\n\n---\n\n## The metamodel\n\nclew 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.\n\n### Artefact layers and build order\n\n19 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.\n\n```mermaid\nflowchart TD\n    classDef business  fill:#FEF3C7,stroke:#D97706,color:#92400E\n    classDef discovery fill:#CCFBF1,stroke:#0D9488,color:#115E59\n    classDef domain    fill:#EDE9FE,stroke:#7C3AED,color:#4C1D95\n    classDef specs     fill:#DBEAFE,stroke:#3B82F6,color:#1E40AF\n    classDef delivery  fill:#D1FAE5,stroke:#10B981,color:#065F46\n    classDef arch      fill:#FEE2E2,stroke:#EF4444,color:#7F1D1D\n    classDef qa        fill:#FEF9C3,stroke:#CA8A04,color:#854D0E\n    classDef qaPlanned fill:#FEF9C3,stroke:#CA8A04,color:#854D0E,stroke-dasharray:4 3\n\n    subgraph DISC[\"Discovery — cross-cutting · pre-formal evidence\"]\n        IDX[\"discovery-idea · IDEA-NNNN\"]:::discovery\n        RES[\"discovery-research\"]:::discovery\n        WS[\"discovery-workshop\"]:::discovery\n    end\n\n    subgraph BA[\"Business Architecture: Step 0 · Steps 1–6 + 4.5\"]\n        S0[\"0 · business-vision · VISION.md · north star\"]:::business\n        S1[\"1 · business-persona · P-NN\"]:::business\n        S2[\"2 · business-model-canvas\"]:::business\n        S3[\"3 · business-capability-map · C-N.M\"]:::business\n        S4[\"4 · business-value-stream · VS-N.M\"]:::business\n        S4b[\"4.5 · business-objective · OBJ-NN · KR-NN.M\"]:::business\n        S5[\"5 · business-process\"]:::business\n        S6[\"6 · business-quantitative-model\"]:::business\n        CL[\"business-competitive-landscape · CO-NN\"]:::business\n    end\n\n    subgraph DOM[\"Domain Layer: Steps 2b · 2c · 7b\"]\n        S2b[\"2b · domain-bounded-context · BC-NN\"]:::domain\n        S2c[\"2c · domain-glossary · BC-NN.GT-NN\"]:::domain\n        S7b[\"7b · domain-model · BC-NN.AGG / ENT / VO / EVT\"]:::domain\n    end\n\n    subgraph PS[\"Product Specs: Steps 7 · 9 · 9.5 · 10\"]\n        S7[\"7 · spec-functional-breakdown-structure · C-N.M.FXX\"]:::specs\n        S9[\"9 · spec-quality-attributes · QA-XXNN\"]:::specs\n        S9_5[\"9.5 · spec-use-case · UC-NN\"]:::specs\n        S10[\"10 · spec-prd · PRD-NNNN\"]:::specs\n    end\n\n    subgraph PLAN[\"Planning: Steps 8 · 11\"]\n        S8[\"8 · plan-delivery-roadmap · E-NN\"]:::delivery\n        S11[\"11 · plan-implementation · Plan-NNNN\"]:::delivery\n    end\n\n    subgraph ARCH[\"Architecture: ADR + Contracts (Steps 7c · 8.5)\"]\n        ADR[\"arch-adr · ADR-NNNN\"]:::arch\n        S7c[\"7c · arch-service-contract · BC-NN.CTR-NN\"]:::arch\n        S8_5[\"8.5 · arch-cli-contract · CLI-NN.CMD-NN\"]:::arch\n    end\n\n    subgraph QA[\"Quality Assurance: post-ship, not a numbered step\"]\n        TS[\"qa-test-strategy · TS-NN\"]:::qa\n        TSC[\"test-scenario (planned)\"]:::qaPlanned\n        TC[\"test-case (planned)\"]:::qaPlanned\n        TP[\"test-plan (planned)\"]:::qaPlanned\n    end\n\n    S0 -.->|\"scopes audience\"| S1\n    S0 -.->|\"frames VP\"| S2\n    S0 -.->|\"sets intent\"| S4b\n    S0 -.->|\"guides\"| S8\n    S1 -->|\"SEGMENTS\"| S2\n    S1 -->|\"informs\"| S3\n    S1 -->|\"TRIGGERS\"| S4\n    S3 -->|\"consumed by\"| S4\n    S4 -->|\"operationalised by\"| S5\n    S2 -->|\"quantified by\"| S6\n    S1 -.->|\"serves outcomes\"| S4b\n    S2 -.->|\"VP intent\"| S4b\n    S4 -->|\"pain informs\"| S4b\n    S4b -.->|\"epics serve\"| S8\n    S4b -.->|\"KR grounds\"| S9\n    S4b -.->|\"traces to\"| S10\n    S3 -->|\"GROUPS_INTO\"| S2b\n    S4 -->|\"SIGNALS\"| S2b\n    S2b -->|\"SCOPES\"| S2c\n    S2b -->|\"MODELS\"| S7b\n    S3 -->|\"inherited by\"| S7\n    S7 -->|\"BECOMES\"| S7b\n    S2c -->|\"names terms\"| S7b\n    S7b -->|\"EXPOSES\"| S7c\n    S7 -->|\"grouped into\"| S8\n    S7 -->|\"surfaced by\"| S8_5\n    S8 -->|\"phases commands\"| S8_5\n    S7b -->|\"referenced by\"| S10\n    S8 -->|\"scopes QA\"| S9\n    S8_5 -.->|\"per-command SLA\"| S9\n    S8_5 -.->|\"referenced by\"| S10\n    S7c -.->|\"referenced by\"| S10\n    S9 -->|\"CONSTRAINS\"| S10\n    S1 -.->|\"ACTOR_OF\"| S9_5\n    S7 -.->|\"realised by\"| S9_5\n    S9_5 -->|\"GROUNDS\"| S10\n    S10 -->|\"DETAILS\"| S11\n    ADR -.->|\"GOVERNS\"| S7c\n    ADR -.->|\"DECIDES\"| S8_5\n    ADR -.->|\"DECIDES\"| S9\n    ADR -.->|\"DECIDES\"| S10\n    CL -.->|\"TARGETS\"| S1\n    CL -.->|\"POSITIONS\"| S2\n    RES -.->|\"validates\"| S1\n    RES -.->|\"validates\"| S2\n    RES -.->|\"validates\"| S6\n    WS -.->|\"aligns\"| S2\n    WS -.->|\"aligns\"| S4\n    IDX -.->|\"graduates to\"| S0\n    S9 -.->|\"defines tests for\"| TS\n    TS -.->|\"scopes\"| TP\n    TP -.->|\"scopes\"| TSC\n    S9_5 -.->|\"realises\"| TSC\n    TSC -.->|\"expands into\"| TC\n    S10 -.->|\"is oracle for\"| TC\n    S11 -.->|\"verified by\"| TP\n```\n\n---\n\n## Architecture\n\nclew has three layers:\n\n```\nAGENT (Claude / Codex)\n  calls clew via Bash → gets deterministic IDs back\n  writes markdown prose referencing those IDs\n\nCLEW CLI (Typer + SQLite)\n  CRUD commands per entity type\n  ID generation via DB sequences, never by the LLM\n  FK enforcement at write time\n  YAML export → snapshot/ for git readability\n\nMARIMO NOTEBOOKS (read-only analysis)\n  Effort estimates + rollup to epics\n  Roadmap / Gantt\n  KR coverage, financial models\n```\n\nUpgrade path: CLI → MCP server → HTTP API, all wrapping the same core layer. See [`docs/architecture/decisions/`](docs/architecture/decisions/) for the full rationale.\n\n---\n\n## Where to start reading\n\nThis 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.\n\nDepending on what you came for:\n\n- **What is clew for?** → [`VISION.md`](docs/VISION.md) + [`docs/business/02a-lean-canvas.md`](docs/business/02a-lean-canvas.md)\n- **Who is it built for?** → [`docs/business/01a-personas.md`](docs/business/01a-personas.md) (P-01 Ava, the agent-first product engineer)\n- **What can it do? (capabilities)** → [`docs/business/03a-capability-map.md`](docs/business/03a-capability-map.md) (5 L0 domains, 19 L1 capabilities)\n- **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)\n- **What are the goals and measures?** → [`docs/business/04b-objectives.md`](docs/business/04b-objectives.md) (3 OKRs, 12 KRs)\n- **Why these technical decisions?** → [`docs/architecture/decisions/`](docs/architecture/decisions/) (ADRs ahead of implementation)\n- **What does the user research say?** → [`docs/discovery/interviews/`](docs/discovery/interviews/) (wave-1 interview + synthesis, N=1, founder-as-instance)\n\nEvery 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.\n\n---\n\n## Status\n\nEarly 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).\n\n## License\n\nMIT\n",
  "bytes": 10317,
  "sha": "e0407946c1d7f2562ba113d0a242ac64f8e904b23d4dfa90cba92877819197dd",
  "repo_slug": "victorhueni/clew",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_victorhueni_clew_docs_index_md_a7faba82/readme"
}