Skip to content

README.md

Latest commit

 

History

History
151 lines (101 loc) · 7.96 KB

README.md

File metadata and controls

151 lines (101 loc) · 7.96 KB
Raw

Minsky documentation

Implementation and operational reference for Minsky — the exocortex / principal substrate the top-level README describes. Strategic memos, position papers, and incident records live in Notion (Minsky workspace); per-task history lives in the Minsky task DB and GitHub PRs. This directory is the code-adjacent layer: setup, configuration, migration, ops, testing patterns, architecture references.

For the brand foundation (locked myth, cultural code, vocabulary), see the minsky-brand skill. For operational tokens (typography, color, motion, contrast), see brand-system.md. For the documentation taxonomy that places each artifact in its slot (ADR / RFC / position paper / engineering guide / architecture reference / etc.), see CLAUDE.md §Documentation Taxonomy.

Getting Started

Core Concepts

Feature Documentation

Session Management

Task Management

MCP Integration

Git Workflows

  • PR Workflow — Pull request preparation and approval workflows

Configuration

Architecture & Development

Development Workflow

Testing

For all testing decisions (where to put tests, how to mock, what to test) see the testing-guide skill (.claude/skills/testing-guide/SKILL.md). Mocking utilities live in src/utils/test-utils/. Architecture-level docs:

Architecture (subdirectory)

Migrations

Conventions

Operations

Reference

Command Categories

  • Session Management: minsky session start|list|get|delete|dir|update|pr|approve
  • Task Management: minsky tasks list|get|create|status|spec|migrate
  • Git Operations: minsky git clone|branch|summary|prepare-pr
  • Rules Management: minsky rules list|get|create|update|search|delete
  • Configuration: minsky config list|show
  • Project Setup: minsky init
  • MCP Server: minsky mcp start

Rules a new project receives

minsky init installs two kinds of rule and tells you which is which:

  • Base rules are not declinable — Minsky's own workflows depend on them.
  • Optional rules are installed too, and you can turn any of them off. init lists them with a one-line description each, on stdout and in the MCP tool result.

Declining is per-rule and reversible at any time:

minsky rules disable --id <id>   # or: minsky rules enable --id <id>
minsky compile              # regenerates .claude/rules, .cursor/rules, AGENTS.md

For scripted or CI onboarding, decide at init time instead — this writes the same config the commands above write:

minsky init --backend minsky --disable json-parsing,git-safety

Optional rules stay installed until you remove them, so a project nobody reviews keeps the full set. minsky rules config shows what is currently selected.

Backend Types

  • Task Backends: minsky, github-issues
  • Repository Backends: local, remote, github
  • Session Storage Backends: postgres only — SQLite was removed (mt#2339; see ADR-018)

Key File Locations

  • Main Configuration: .minsky/config.yaml
  • Task Specs: stored in the Minsky task DB (browse via mcp__minsky__tasks_*)
  • Rules Directory: .cursor/rules/ (Cursor format) or .minsky/rules/ (generic)
  • Session Storage: ~/.local/state/minsky/sessions/
  • AI Agent Memory: ~/.claude/projects/.../memory/ (per-machine, not committed)

Contributing to Documentation

When updating documentation:

  • Keep examples runnable against the current codebase. If a doc claims a tool/utility exists, verify it does.
  • Update cross-references when moving content; broken links are surfaced by the stale-reference checklist.
  • Prefer linking from this index over duplicating content in multiple places.
  • Per-machine, ephemeral, or task-specific documentation does not belong here — that lives in tasks (DB), PRs (GitHub), or memories.

For per-cluster cleanup history, see PRs filed under mt#1319 / mt#1360.