Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
176 lines (145 loc) · 6.66 KB

ARCHITECTURE.md

File metadata and controls

176 lines (145 loc) · 6.66 KB

mogkit — Architecture

System shape and fixed technical decisions. Do not substitute choices marked Decided.

Stack (Decided)

Layer Choice Rationale
Repo Single monorepo, MIT One contribution surface
Monorepo tooling pnpm workspaces Lightweight; no Nx/Turbo at this scale
CLI TypeScript, Node 20+ Frictionless npx; pairs with Claude Code
CLI commands commander Mature, minimal
CLI prompts @clack/prompts Friendly visual prompts for less terminal-fluent PMs
Skills Plain markdown (SKILL.md) Portable, contributable, agent-agnostic
Knowledge graph store JSON file + generated graph.md No DB; inspectable, diffable, git-friendly
Site Astro + content collections + MDX + Tailwind Static; content-heavy ed-tech is a content problem
Site search Pagefind Static, no backend
Workflow Library feed Astro content collection + RSS "Latest" = newest-first sort; no live backend
Hosting Netlify (site) · npm (CLI) Standard distribution
CI GitHub Actions Lint, typecheck, build, test, schema-validate

No web app. No hosted compute. No backend. No accounts. Tooling is fully local; the site is fully static.

The two-tier skill model

Skills come in two tiers. The distinction is load-bearing — Claude Code must not blur it.

Tier A — Standalone skills

Single-shot utilities. Input: something the PM pastes (a spec, a goal, a transcript). Output: a reasoning scaffold. No corpus, no graph, no state, no CLI required. A PM copies the SKILL.md into .claude/skills/ and uses it immediately. Standalone skills span all five wedges. Built in Phase 1.

Tier B — The Discovery knowledge engine

A stateful, multi-step, corpus-backed system. Skills operate on a shared sources/ corpus and a graph/graph.json knowledge graph. This is the only deep system, and it is Discovery-only. Built in Phase 3.

Why the split exists: it lets the project have wedge breadth (Tier A) without faking a deep system per wedge (which would be shallow and generic). See VISION-AND-PRINCIPLES.md principle 4.

Repository layout

mogkit/
├─ README.md  CONTRIBUTING.md  LICENSE
├─ pnpm-workspace.yaml  package.json
├─ .github/workflows/ci.yml
│
├─ docs/                         # the six context documents
│
├─ skills/
│  ├─ SKILL-SPEC.md
│  ├─ _example/SKILL.md
│  ├─ standalone/                # Tier A
│  │  ├─ metrics-tree/SKILL.md
│  │  ├─ spec-stress-test/SKILL.md
│  │  ├─ narrative-review/SKILL.md
│  │  ├─ tradeoff-frame/SKILL.md
│  │  ├─ stakeholder-map/SKILL.md
│  │  ├─ launch-readiness/SKILL.md
│  │  └─ interview-coach/SKILL.md
│  └─ discovery/                 # Tier B
│     ├─ graphify/SKILL.md
│     ├─ discovery-query/SKILL.md
│     ├─ assumption-audit/SKILL.md
│     ├─ prd-interrogate/SKILL.md
│     ├─ interview-guide/SKILL.md
│     └─ synthesis-map/SKILL.md
│
├─ cli/
│  ├─ package.json               # published as `mogkit`
│  ├─ src/
│  │  ├─ index.ts
│  │  ├─ commands/ { init, add, status, skills, doctor }.ts
│  │  ├─ lib/ { workspace, corpus, health, skills-registry }.ts
│  │  └─ templates/ { CLAUDE.md, gitignore }
│  └─ test/
│
├─ engine/
│  ├─ graph-schema.json
│  └─ sample-corpus/
│
└─ site/
   ├─ astro.config.mjs
   ├─ src/
   │  ├─ content/
   │  │  ├─ wedges/              # one MDX per wedge (5)
   │  │  ├─ workflows/           # the Workflow Library
   │  │  └─ material/            # curated external resources
   │  ├─ pages/ { index, setup, wedges/[slug], workflows/[slug], workflows/index }.astro
   │  └─ components/
   └─ public/

The PM workspace (created by mogkit init)

my-workspace/
├─ .git/
├─ CLAUDE.md            # encodes the principles; orients every Claude Code session
├─ .gitignore
├─ .claude/skills/      # installed skills
├─ sources/             # raw research; versioned; grows over time
├─ graph/               # graph.json + graph.md (generated by graphify)
└─ knowledge/           # outputs of the interrogation skills

CLI command reference

mogkit init [dir]      Scaffold a workspace; git init; install Discovery skills
mogkit add             Interactive: ingest files into sources/, tag by type
mogkit status          Corpus health report — count, type spread, rating, gaps
mogkit skills list     List available skills + install state
mogkit skills add <n>  Install a skill into .claude/skills/
mogkit doctor          Verify Claude Code + skills setup; plain-language fixes

The CLI does no LLM work. After init, the PM opens Claude Code in the workspace and runs skills.

The knowledge graph schema

graph/graph.json, validated by engine/graph-schema.json.

{
  "meta": {
    "generated": "ISO-8601",
    "sourceCount": 6,
    "sourceTypes": ["interview", "ticket", "prd"],
    "health": "thin"
  },
  "nodes": [
    {
      "id": "pain-001",
      "type": "Pain",
      "label": "Onboarding takes >2 weeks for new validators",
      "provenance": [
        { "source": "sources/interview-03.md", "quote": "...", "loc": "L42" }
      ]
    }
  ],
  "edges": [
    {
      "from": "segment-001",
      "to": "pain-001",
      "type": "experiences",
      "provenance": [{ "source": "sources/interview-03.md", "quote": "...", "loc": "L44" }]
    }
  ]
}

Node types: Person, Segment, Pain, Need (JTBD), Feature, Competitor, Insight, Assumption, Quote, Outcome. Edge types: experiences, requests, blocks, contradicts, supports, belongs-to, competes-with, evidences, assumes.

Rules

  • Every node and edge carries a non-empty provenance array — except Assumption nodes, whose empty provenance is the point and must be explicit.
  • health is derived: thin (< 8 sources or a single source type), developing, rich. Skills gate confidence on this value.

Content model (site)

Three Astro content collections, each with a typed schema:

  • wedges/ — five MDX files, one per PM wedge. Fields: title, slug, order, summary, problem, skills (slugs), material (refs). Evergreen craft education.
  • workflows/ — the Workflow Library. Schema and authoring rules in WORKFLOW-FEED-SPEC.md. Newest-first; RSS-backed.
  • material/ — curated external resources (Torres, Cagan, Lenny, named operators). Fields: title, url, author, wedge, why (one line on why it's worth the PM's time). Curated paths, never link dumps.