mirror of https://github.com/himanshudongre/smriti.git synced 2026-08-28 05:14:59 +00:00

Himanshu Dongre f4062da76e Sync docs and regenerate skill pack for the current product surface

Packaging/readiness pass — documentation only, no feature or behavior change.

- REPO_STRUCTURE.md, CONTRIBUTING.md: corrected test counts (156 integration,
  133 unit, 151 CLI), local-first setup flow (make setup-local / dev-local),
  command count, new routes/types/test files.
- README.md: refreshed dogfood metrics, added Project Current State and
  smriti doctor to the surfaces, SQLite to the tech stack.
- cli/README.md: MCP tool count 17 -> 21 (added the four worktree tools),
  documented the smriti worktree commands.
- ARCHITECTURE.md: API table now lists the Project Current State and metrics
  endpoints; new Database modes section (local SQLite / Postgres).
- DECISIONS.md: recorded the local-first SQLite mode and Project Current
  State surface decisions.
- AGENTS.md: regenerated from skill pack template v2.3 (was a stale v1.5
  render); the .claude/ claude-code render was likewise refreshed locally.

.env.example, docs/DEMO_SCRIPT.md, and CLAUDE.md were reviewed and left as-is.

2026-05-17 00:03:59 +05:30

4.9 KiB

Raw Blame History

Contributing to Smriti

Thanks for your interest in contributing. This document covers how to get the dev environment running, how to run tests, and how to propose changes.

Dev environment

Prerequisites: Python 3.11+, Node 18+. Docker is optional — needed only for Postgres (shared/team) mode.

git clone https://github.com/himanshudongre/smriti
cd smriti

cp .env.example .env
# Edit .env to add your API keys (OpenAI, Anthropic, or both).
# Leave keys commented out to use mock mode (no real LLM calls).

make setup-local                 # backend venv + deps + CLI + frontend (no Docker)

# Start backend (terminal 1)
make dev-local

# Start frontend (terminal 2)
make dev-frontend

make setup-local runs Smriti in local-first SQLite mode — no Docker, no Postgres; state lives in ~/.smriti/smriti.db. It installs the backend, the CLI (smriti + smriti-mcp), and the frontend. For Postgres-backed shared/team mode, use make setup-postgres + make dev-postgres instead. The CLI is installed into the backend venv at backend/.venv/bin/. Activate the venv to use it from your shell:

source backend/.venv/bin/activate

Open http://localhost:5173 for the chat UI.

Running tests

# All backend tests (uses mock provider — no API key required)
make test

# CLI + MCP tests (CLI is already installed by make setup)
cd cli && pytest

# TypeScript typecheck
cd frontend && npx tsc --noEmit

# Frontend production build
cd frontend && npm run build

The backend integration test suite uses the deterministic mock adapter and an in-memory SQLite database (via conftest.py). No live API keys are needed.

The CLI test suite (cli/tests/) covers MCP tool handlers, skill pack rendering and installation, multi-branch state formatting, and content-integrity guards for the skill pack template. CLI tests use MagicMock(spec=SmritiClient) fixtures — no running backend required.

When to run which tests:

Changed area	Run
`backend/app/`	`make test` (156 integration + 133 unit tests)
`cli/smriti_cli/`	`cd cli && pytest` (151 tests)
`cli/smriti_cli/skill_pack/template.md`	`cd cli && pytest tests/test_skill_pack.py` — content-integrity tests catch dropped sections
`frontend/src/`	`cd frontend && npx tsc --noEmit`
Both backend + CLI	Both suites — they share no test infrastructure but both call the same backend API

Code style

Backend: Python code is formatted and linted with ruff.

make lint       # Check
make format     # Fix in place

Frontend: TypeScript with strict type checking. ESLint is configured but not enforced in CI yet.

There are no hard style rules beyond what ruff and tsc enforce. Prefer clarity over brevity. Keep functions short. Do not add comments that restate the code — only comment non-obvious decisions.

Making changes

Fork the repo and create a feature branch.
Make your changes. Keep commits focused: one logical change per commit.
Run backend tests and frontend typecheck before opening a PR.
Open a PR against main. Describe what changed and why.

For larger changes (new feature, API change, refactor), open an issue first to discuss scope before writing code.

Reporting bugs

Open a GitHub issue. Include:

What you expected to happen
What actually happened
Steps to reproduce (minimal, if possible)
Relevant log output (make logs for Docker, or terminal output)
Backend version (git hash or tag)

Contributing demos and docs

Docs live in docs/ and at the repo root (README.md, ARCHITECTURE.md, DECISIONS.md). Demo scenarios live in demos/.

For doc fixes: open a PR directly. For new demo scenarios: follow the structure in demos/branching-reasoning-demo/ — a README, RUNBOOK, DEMO_SCRIPT, and EXPECTED_OUTCOMES at minimum.

Agent-facing surfaces

Smriti has three agent-facing surfaces beyond the chat UI:

CLI (cli/smriti_cli/main.py) — smriti command, 14 commands
MCP server (cli/smriti_cli/mcp_server.py) — smriti-mcp command, 21 tools
Skill pack (cli/smriti_cli/skill_pack/) — versioned instruction files for Claude Code and Codex

Changes to any of these should include corresponding test coverage in cli/tests/. Skill pack content changes should pass the content-integrity tests in test_skill_pack.py — these assert that critical sections (anti-patterns, signal test, drift detection, work claims) cannot be silently dropped by template edits.

What we are not looking for

Automatic checkpointing logic — Checkpoints are intentionally manual.
Authentication / multi-user support — deferred by design.
Generic orchestration or task management — work claims are advisory and narrow.
Changes to legacy V1 endpoints — these are retained for compatibility only.

If you want to work on something that falls outside normal scope, open an issue first.

4.9 KiB Raw Blame History