Quipu

Your project, encoded in connected threads of knowledge.

Quipu is an opinionated starter + CLI for Claude Code projects built on top of RuFlo. It scaffolds a new project with battle-tested conventions: Karpathy-first philosophy, 30 canonical agents, 65 skills, 24 hooks, 3-layer memory (sql.js → RuVector PostgreSQL + GNN), 5 security layers, and a 10-lesson learning path.

Install:

# Option 1: create new project directory
npx @okuanb/quipu@alpha init my-app
cd my-app
claude

# Option 2: initialize in current directory (e.g. existing claude-flow project)
cd existing-project
npx @okuanb/quipu@alpha init .
claude

That's it. Claude Code reads CLAUDE.md automatically and follows the workflow kernel: brainstorming → writing-plans → subagent-driven-development → TDD → verification-before-completion.

Why Quipu

The Inca quipu was a system of knotted cords that encoded information — nodes connected by threads. Quipu (the starter) works the same way: your project's knowledge lives in embeddings (nodes), GNN edges (threads), and persistent memory (the quipu itself). Agents read the threads, extend them, and learn from them across sessions.

Built by distilling 6 expert repositories:

• andrej-karpathy-skills — first-principles code philosophy
• everything-claude-code — harness-first + eval-first patterns
• superpowers — workflow kernel (TDD, subagents, verification)
• claude-code-patterns — production PRO TIPS
• claude-howto — canonical curriculum for hooks/plugins/checkpoints
• ruflo — 60+ agents, RuVector, ReasoningBank

The fusion was done via a swarm of 15 elite agents over 6 sprints. See the postmortem.

What you get

my-app/
├── CLAUDE.md                  # generated from template (Karpathy + RuFlo)
├── CLAUDE.local.md            # private overrides (gitignored)
├── CONTEXT.md                 # domain glossary (ubiquitous language)
├── ARCHITECTURE.md            # bounded contexts + ADRs reference
├── .gitignore                 # baseline ignoring secrets + local overrides
├── .claude/
│   ├── agents/                # 30 canonical agents in 7 buckets
│   ├── skills/                # 35 skills (20 kernel + 15 opt-in)
│   ├── settings.json          # 12 default hooks
│   ├── settings.local.json    # 6 opt-in hooks (gitignored)
│   ├── hooks/                 # 22 hook scripts
│   └── memory.db              # L2 sql.js with 9 namespaces seeded
├── scripts/                   # linters, validators, init helpers
├── tests/                     # test suites (syntax, lint, hooks, security)
└── .github/workflows/         # smoke, release, signing-smoke

Initializing in an existing project

If your project already has Claude Code or claude-flow set up, you can overlay quipu without losing your work:

cd your-existing-project
npx @okuanb/quipu@alpha init .

Quipu will:

• Copy .claude/skills/, .claude/agents/, .claude/hooks/ (additive)
• Copy CLAUDE.md, CONTEXT.md, ARCHITECTURE.md, CLAUDE.local.md, .gitignore to the project root only if they do not already exist (your work is preserved)
• Initialize 9 memory namespaces in .claude/memory.db
• Skip any file already present (logged as skip <file> (already exists, preserved))

This is the recommended path for adopting quipu on an existing repo.

Feature Development Workflow (Pocock alignment cycle)

Quipu eliminates vibe coding. Every change follows one of two paths before a single line of production code is written.

Enhancement path (new features, improvements):

/setup-matt-pocock-skills -> /grill-me -> /to-prd -> /to-issues -> tdd-workflow

Fix path (bugs, regressions):

/triage -> /grill-me (conditional) -> /diagnose (6 phases) -> tdd-workflow regression

Use /start-feature or /start-fix to walk the full path with gates enforced automatically.

Reference: docs/diagrams/workflow-overview.drawio

Features

Feature	Detail
Karpathy-first philosophy	4 principles (Think · Simplicity · Surgical · Goal-driven) hard-baked in CLAUDE.md
Workflow kernel	brainstorming → plans → subagent-driven dev → TDD → verification gate
30 canonical agents	7 buckets: core, review, arch, security, ops, coord, meta
65 skills	20 universal kernel + 45 opt-in (enable per project)
24 hooks pipeline	12 default ON + 6 opt-in + 6 security/memory, budget ≤2s hot-path
3-layer memory	L1 session · L2 sql.js local · L3 RuVector PostgreSQL with GNN (opt-in)
5 security layers	AIMDS prompts · sandbox tools · PII/secrets · CVE/SBOM · truth-score outputs
OWASP LLM 10/10	Full coverage of LLM Top 10 threats
ReasoningBank loop	RETRIEVE → EXECUTE → JUDGE → DISTILL → CONSOLIDATE → REPLAY
Telemetry F-10	8 events with p50/p95/p99 probabilistic bands
Learning path	10 lessons (14h total) + 30-question self-assessment quiz
Pocock alignment cycle	Mandatory grilling + PRD before any production code (Enhancement/Fix paths)
Scope Guardian Phase 2	scope-enforce blocks file mutations outside scope; conscious-override via env var

Scope Guardian (Phase 2)

Real enforcement on Edit, Write, and MultiEdit via PreToolUse hook.

• Blocks paths outside .swarm/scope.json allowed_paths
• Blocks protected_paths (.env, secrets, settings.json) unconditionally
• Override via RUFLO_SCOPE_OVERRIDE=1 env var (action is logged)
• Runs in mode=warn during the 7-day calibration window; flip to mode=block after

Requirements

• Claude Code ≥ 2.0.65
• RuFlo / claude-flow ≥ 3.5.65 (installed globally)
• Node.js ≥ 20
• PostgreSQL with RuVector extension (optional, for L3 shared memory)

Documentation

• Learning path (10 lessons)
• PRD — 10 features · 40 acceptance criteria
• Work plan — 6 sprints × 2 weeks
• Rollout plan α/β/GA
• Postmortem
• Troubleshooting — 15+ known foot-guns
• Panorama diagram — architecture overview

Philosophy

Think before coding · Simplicity first · Surgical changes · Goal-driven execution.

— Karpathy, distilled into 65 lines of CLAUDE.md that your project inherits.

Quipu is deliberately conservative. If a rule stops being enforced, prune — do not add more emphasis. If a file grows beyond 500 lines, split it. If a CLAUDE.md grows beyond 300 lines, the linter fails.

Status

Alpha (v1.0.0-alpha.4). Rollout timeline:

• Alpha: published, iterating (since 2026-04-30)
• Beta: TBD post calibration window
• GA: TBD

License

MIT © Orlando Kuan