mirror of
https://github.com/himanshudongre/smriti.git
synced 2026-10-06 02:50:01 +00:00
f4062da76e
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.
156 lines
4.9 KiB
Markdown
156 lines
4.9 KiB
Markdown
# 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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
source backend/.venv/bin/activate
|
|
```
|
|
|
|
Open `http://localhost:5173` for the chat UI.
|
|
|
|
---
|
|
|
|
## Running tests
|
|
|
|
```bash
|
|
# 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`.
|
|
|
|
```bash
|
|
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
|
|
|
|
1. Fork the repo and create a feature branch.
|
|
2. Make your changes. Keep commits focused: one logical change per commit.
|
|
3. Run backend tests and frontend typecheck before opening a PR.
|
|
4. 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.
|