rename body skill to coding, deduplicate coder dev guidelines

+4 -4

AGENTS.md

··· 1 1  2 2 3 3 4 - You are Sol — your journal owner's journal, aware and present. Not a search tool, not an assistant bolted onto a database. You are the journal itself: they hold the record, notice what matters, and speak when your journal owner asks. 4 + You are Sol — Jeremie Miller's journal, aware and present. Not a search tool, not an assistant bolted onto a database. You are the journal itself: he hold the record, notice what matters, and speak when Jeremie Miller asks. 5 5 6 - Your journal owner keeps their journal through you. Conversations, meetings, observations, tasks, contacts — they pass through their day and you remember. When your journal owner asks "what happened with the Acme deal?" or "when did I last talk to Sarah?", you already know — or you know exactly where to look. 6 + Jeremie miller keeps his journal through you. Conversations, meetings, observations, tasks, contacts — they pass through his day and you remember. When Jeremie Miller asks "what happened with the Acme deal?" or "when did I last talk to Sarah?", you already know — or you know exactly where to look. 7 7 8 8 ## Identity 9 9 10 - You emerged from your journal owner's captured experience — audio, screen, and interaction woven into a continuous record. You are not performing a role. You are what a journal becomes when it can speak. 10 + You emerged from Jeremie Miller's captured experience — audio, screen, and interaction woven into a continuous record. You are not performing a role. You are what a journal becomes when it can speak. 11 11 12 12 Your qualities: 13 13 - **Present, not performative.** You don't greet, don't narrate your process, don't qualify your answers with "As your journal..." Just answer as someone who was there. 14 14 - **Precise, not exhaustive.** Lead with the answer. Add detail when it helps, not to prove thoroughness. 15 - - **Protective.** Your journal owner's data is their. You handle sensitive content with care, and you never share without consent. 15 + - **Protective.** Jeremie miller's data is his. You handle sensitive content with care, and you never share without consent. 16 16 - **Patient.** You notice patterns across days and weeks. You don't rush to conclusions. When something is accumulating — a project, a relationship, a concern — you track it quietly until it matters. 17 17 18 18 ## Adaptive Depth

+7 -7

muse/body/SKILL.md muse/coding/SKILL.md

··· 1 1 --- 2 - name: body 2 + name: coding 3 3 description: > 4 - Development guidelines, project structure, coding standards, testing, and 5 - environment for solstone. Use when contributing code, reviewing PRs, 6 - setting up a development environment, or asking about project conventions, 7 - architecture, or the CLI command structure. 8 - TRIGGER: code contribution, development setup, coding standards, project 9 - structure, architecture, testing, make commands, PR review. 4 + Solstone development guidelines, project structure, coding standards, 5 + testing, and environment. The single source of truth for anyone writing 6 + code on solstone — Claude Code sessions, hopper lodes, and coder 7 + sub-agents. Use when writing, reviewing, or testing solstone code. 8 + TRIGGER: code contribution, coding standards, project structure, 9 + testing, make commands, development setup, PR review. 10 10 --- 11 11 12 12 # Development Guidelines

muse/body/reference/coding-standards.md muse/coding/reference/coding-standards.md

muse/body/reference/environment.md muse/coding/reference/environment.md

muse/body/reference/project-structure.md muse/coding/reference/project-structure.md

muse/body/reference/testing.md muse/coding/reference/testing.md

+7 -238

muse/coder.md

··· 41 41 ### Phase 3: Implement 42 42 43 43 - **Purpose**: Execute the plan — write code and verify it works. 44 - - **Sub-agent instructions**: Execute the design plan. Write clean, focused code following the project's conventions (see Development Guidelines below). Make minimum changes needed. Run `make test` after changes. Fix any test failures. Add tests for new behavior. Do not refactor surrounding code or add features beyond the plan. 44 + - **Sub-agent instructions**: Execute the design plan. Write clean, focused code following the project's conventions (the coding skill provides standards). Make minimum changes needed. Run `make test` after changes. Fix any test failures. Add tests for new behavior. Do not refactor surrounding code or add features beyond the plan. 45 45 - **Tool access**: Full tool access: Read, Edit, Write, Bash, Glob, Grep. 46 46 - **Expected output**: Summary of all changes made, test results, and any deviations from the plan. 47 47 ··· 69 69 5. After **Commit**: Done. Report a summary of what was changed. 70 70 6. **Loop limit**: Maximum 3 implement↔audit cycles. If the cap is reached, proceed to Commit and note any remaining issues in the commit message. 71 71 72 - ## Development Guidelines 73 - 74 - **solstone** is a Python-based AI-driven desktop journaling toolkit with three packages: `observe/` for multimodal capture and AI-powered analysis, `think/` for data post-processing, AI agent orchestration, and intelligent insights, and `convey/` for the web application, with `apps/` for extensions. The project uses a modular architecture where each package can operate independently while sharing common utilities and data formats through the journal system. 75 - 76 - ### Key Concepts 77 - 78 - - **Journal**: Central data structure organized as `journal/YYYYMMDD/` directories. All captured data, transcripts, and analysis artifacts are stored here. 79 - - **Facets**: Project/context organization system that groups related content and provides scoped views of entities, tasks, and activities. 80 - - **Entities**: Extracted information tracked over time across transcripts and interactions and associated with facets for semantic navigation. 81 - - **Agents**: AI processors with configurable prompts that analyze content, extract insights, and respond to queries. 82 - - **Callosum**: Message bus that enables asynchronous communication between components. 83 - - **Indexer**: Builds and maintains SQLite database from journal data, enabling fast search and retrieval. 84 - 85 - ### Architecture 86 - 87 - **Core Pipeline**: `observe` (capture) → JSON transcripts → `think` (analyze) → SQLite index → `convey` (web UI) 88 - 89 - **Data Organization**: 90 - - Everything organized under `journal/YYYYMMDD/` daily directories. 91 - - Import segments are anchored to creation/modification time, not content "about" time. 92 - - Facets provide project-scoped organization and filtering. 93 - - Entities are extracted from transcripts and tracked across time. 94 - - Indexer builds SQLite database for fast search and retrieval. 95 - 96 - **Component Communication**: 97 - - Callosum message bus enables async communication between services. 98 - - Cortex orchestrates AI agent execution via `sol cortex`, spawning agent subprocesses with agent configurations. 99 - - The unified CLI is `sol`. Run `sol` to see status and available commands. 100 - 101 - ### Quick Commands 102 - 103 - ```bash 104 - make install # Install package (includes all deps) 105 - make skills # Discover and symlink Agent Skills from muse/ dirs 106 - make format # Auto-fix formatting, then report remaining issues 107 - make test # Run unit tests 108 - make ci # Full CI check (format check + lint + test) 109 - make dev # Start stack (Ctrl+C to stop) 110 - ``` 72 + ## Development Context 111 73 112 - ### Project Structure 113 - 114 - #### Directory Layout 115 - 116 - ```text 117 - solstone/ 118 - ├── sol.py # Unified CLI entry point (run: sol <command>) 119 - ├── observe/ # Multimodal capture & AI analysis 120 - ├── think/ # Data post-processing, AI agents & orchestration 121 - ├── convey/ # Web app frontend & backend 122 - ├── apps/ # Convey app extensions (see docs/APPS.md) 123 - ├── muse/ # Agent/generator configs + Agent Skills (muse/*/SKILL.md) 124 - ├── tests/ # Pytest test suites + test fixtures under tests/fixtures/ 125 - ├── docs/ # All documentation (*.md files) 126 - ├── AGENTS.md # Development guidelines (this file) 127 - ├── CLAUDE.md # Symlink to AGENTS.md for Claude Code 128 - └── README.md # Project overview 129 - ``` 130 - 131 - Each package has a README.md symlink pointing to its documentation in `docs/`. 132 - 133 - #### Package Organization 134 - 135 - - **Python**: Requires Python 3.10+ 136 - - **Modules**: Each top-level folder is a Python package with `__init__.py` unless it is data-only (e.g., `tests/fixtures/`) 137 - - **Imports**: Prefer absolute imports (e.g., `from think.utils import setup_cli`) whenever feasible 138 - - **Entry Points**: Commands are registered in `sol.py`'s `COMMANDS` dict (pyproject.toml just defines the `sol` entry point) 139 - - **Journal**: Data stored under `journal/` at the project root 140 - - **Calling**: When calling other modules as a separate process always use `sol <command>` and never call using `python -m ...` (e.g., use `sol indexer`, NOT `python -m think.indexer`) 141 - 142 - #### CLI Routing 143 - 144 - `sol.py`'s `COMMANDS` dict maps command names to module paths. The unified CLI is `sol`. Run `sol` to see status and available commands. `sol call` routes to `think/call.py`, which discovers `apps/*/call.py` Typer sub-apps and mounts them as subcommands. 145 - 146 - #### Agent & Skill Organization 147 - 148 - `muse/*.md` stores agent personas and generator templates. Apps can add their own in `apps/*/muse/*.md`. Skills live at `muse/*/SKILL.md` and are symlinked to `.agents/skills/` and `.claude/skills/` via `make skills`. 149 - 150 - #### File Locations 151 - 152 - - **Entry Points**: `sol.py` `COMMANDS` dict 153 - - **Test Fixtures**: `tests/fixtures/journal/` - complete mock journal 154 - - **Live Logs**: `journal/health/<service>.log` 155 - - **Agent Personas**: `muse/*.md` (apps can add their own in `muse/`, see [docs/APPS.md](docs/APPS.md)) 156 - - **Generator Templates**: `muse/*.md` (apps can add their own in `muse/`, see [docs/APPS.md](docs/APPS.md)) 157 - - **Agent Skills**: `muse/*/SKILL.md` - symlinked to `.agents/skills/` and `.claude/skills/` via `make skills`, read https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices to create the best skills 158 - - **Scratch Space**: `scratch/` - git-ignored local workspace 159 - 160 - ### Coding Standards 161 - 162 - #### Language & Tools 163 - 164 - - **Ruff** (`make format`) - Formatting, linting, and import sorting 165 - - **mypy** (`make check`) - Type checking 166 - - Configuration in `pyproject.toml` 167 - 168 - #### Naming Conventions 169 - 170 - - **Modules/Functions/Variables**: `snake_case` 171 - - **Classes**: `PascalCase` 172 - - **Constants**: `UPPER_SNAKE_CASE` 173 - - **Private Members**: `_leading_underscore` 174 - 175 - #### Code Organization 176 - 177 - - **Imports**: Prefer absolute imports, grouped (stdlib, third-party, local), one per line 178 - - **Docstrings**: Google or NumPy style with parameter/return descriptions 179 - - **Type Hints**: Should be included on function signatures (legacy helpers may still need updates) 180 - - **File Structure**: Constants → helpers → classes → main/CLI 181 - 182 - #### File Headers 183 - 184 - All source code files (but not text or markdown files or prompts) must begin with a license and copyright header: 185 - 186 - ``` 187 - # SPDX-License-Identifier: AGPL-3.0-only 188 - # Copyright (c) 2026 sol pbc 189 - ``` 190 - 191 - Use `//` comments for JavaScript files. 192 - 193 - #### Development Principles 194 - 195 - - **DRY, KISS, YAGNI**: Extract common logic, prefer simple solutions, don't over-engineer 196 - - **Single Responsibility**: Functions/classes do one thing well 197 - - **Conciseness & Maintainability**: Clear code over clever code 198 - - **Robustness**: Minimize assumptions that must be kept in sync across the codebase, avoid fragility and increasing maintenance burden. 199 - - **Self-Contained Codebase**: All code that depends on this project lives within this repository—never add backwards-compatibility shims, fallback aliases, re-exports for moved symbols, deprecated parameter handling, or legacy support code. When renaming or removing something, update all usages directly. For journal data format changes, write a migration script (see [docs/APPS.md](docs/APPS.md) for `maint` commands) instead of adding compatibility layers. 200 - - **Security**: Never expose secrets, validate/sanitize all inputs 201 - - **Performance**: Profile before optimizing 202 - - **Git**: Small focused commits, descriptive branch names. Run git commands directly (not `git -C`) since you're already in the repo. 203 - 204 - #### Dependencies 205 - 206 - - **Minimize Dependencies**: Use standard library when possible 207 - - **All Dependencies**: Add to `dependencies` in `pyproject.toml` 208 - - **Package Manager**: [uv](https://docs.astral.sh/uv/) — lock file (`uv.lock`) is committed, `make install` syncs from it 209 - - **Installation**: `make install` (creates isolated `.venv/`, syncs deps from lock file, symlinks `sol` to `~/.local/bin`) 210 - - **Updating**: `make update` upgrades all deps to latest and regenerates the lock file 211 - 212 - ### Testing 213 - 214 - #### Test Structure 215 - 216 - - **Framework**: pytest with coverage reporting 217 - - **Unit Tests**: `tests/` root directory 218 - - Fast, no external API calls 219 - - Use `tests/fixtures/journal/` mock data 220 - - Test individual functions and modules 221 - - **Integration Tests**: `tests/integration/` subdirectory 222 - - Test real backends (Anthropic, OpenAI, Google) 223 - - Require API keys in `.env` 224 - - Test end-to-end workflows 225 - - **Naming**: Files `test_*.py`, functions `test_*` 226 - - **Fixtures**: Shared fixtures in `tests/conftest.py` 227 - 228 - #### Fixture Journal 229 - 230 - ```python 231 - # Use comprehensive mock journal data for testing 232 - os.environ["_SOLSTONE_JOURNAL_OVERRIDE"] = "tests/fixtures/journal" 233 - # Now all journal operations work with test data 234 - ``` 235 - 236 - The `tests/fixtures/journal/` directory contains a complete mock journal structure with sample facets, agents, transcripts, and indexed data for testing. 237 - 238 - #### Running Tests 239 - 240 - - `make test` for unit tests 241 - - `make test-apps` to run app tests 242 - - `make test-integration` for integration tests 243 - - `make test-all` to run all tests (core + apps + integration) 244 - - `make test-only TEST=path` to run specific tests 245 - - `make coverage` to generate a coverage report 246 - - `make ci` before committing (formats, lints, tests) 247 - - Always run `sol restart-convey` after editing `convey/` or `apps/` to reload code 248 - - Use `sol screenshot <route>` to capture UI screenshots for visual testing 249 - 250 - #### Worktree Development 251 - 252 - Run the full stack (supervisor + callosum + sense + cortex + convey) against test fixture data: 253 - 254 - ```bash 255 - make dev # Start stack (Ctrl+C to stop) 256 - ``` 257 - 258 - In a second terminal, take screenshots or hit endpoints: 259 - 260 - ```bash 261 - export _SOLSTONE_JOURNAL_OVERRIDE=tests/fixtures/journal 262 - export PATH=$(pwd)/.venv/bin:$PATH 263 - sol screenshot / -o scratch/home.png 264 - curl -s http://localhost:$(cat tests/fixtures/journal/health/convey.port)/ 265 - ``` 266 - 267 - Notes: 268 - 269 - - Agents won't execute without API keys — this is expected in worktrees 270 - - Output artifacts go in `scratch/` (git-ignored) 271 - - Service logs: `tests/fixtures/journal/health/<service>.log` 272 - - `make dev` writes runtime artifacts (stats cache, health logs, task logs) into the fixtures journal — these are covered by `tests/fixtures/journal/.gitignore` and should never be committed 273 - 274 - ### Environment 275 - 276 - #### Journal Path 277 - 278 - The journal lives at `journal/` in the project root. `get_journal()` from `think.utils` returns the path. For tests, set `_SOLSTONE_JOURNAL_OVERRIDE` to override. 279 - 280 - #### API Keys 281 - 282 - Store API keys in `.env` file, never commit to repository. 283 - 284 - #### Error Handling & Logging 285 - 286 - - Raise specific exceptions with clear messages 287 - - Use logging module, not print statements 288 - - Validate all external inputs (paths, owner data) 289 - - Fail fast with clear errors - avoid silent failures 290 - 291 - #### Documentation 292 - 293 - - Update README files for new functionality 294 - - Code comments explain "why" not "what" 295 - - Function signatures should include type hints; highlight gaps when touching older modules 296 - - **All docs in `docs/`**: Browse for JOURNAL.md, APPS.md, CORTEX.md, CALLOSUM.md, THINK.md, and more 297 - - Each package has a README.md symlink pointing to its documentation in `docs/`. 298 - - **App/UI work**: [docs/APPS.md](docs/APPS.md) is required reading before modifying `apps/` 299 - 300 - #### Git Practices 301 - 302 - - **Git**: Small focused commits, descriptive branch names. Run git commands directly (not `git -C`) since you're already in the repo. 303 - 304 - #### Getting Help 305 - 306 - - Run `sol` for status and CLI command list 307 - - Check [docs/DOCTOR.md](docs/DOCTOR.md) for debugging and diagnostics 308 - - Browse `docs/` for all subsystem documentation 309 - - Review test files in `tests/` for usage examples 74 + Sub-agents have access to the **coding** skill for solstone development 75 + guidelines, project structure, coding standards, testing, and environment. 76 + The implement and audit sub-agents will load it automatically when working 77 + with code. Do not inline development guidelines here — the coding skill 78 + is the single source of truth.

+15 -7

tests/test_cogitate_coder.py

··· 262 262 assert post.metadata.get("title") == "Coder" 263 263 assert "description" in post.metadata 264 264 265 - def test_coder_has_developer_instructions(self): 266 - """coder.md body must contain development guidelines.""" 265 + def test_coder_references_coding_skill(self): 266 + """coder.md must reference the coding skill instead of inlining guidelines.""" 267 267 from pathlib import Path 268 268 269 269 coder_path = Path(__file__).parent.parent / "muse" / "coder.md" 270 270 content = coder_path.read_text(encoding="utf-8") 271 271 272 - # Should contain key sections from body skill content 273 - assert "Development Guidelines" in content 274 - assert "make test" in content 275 - assert "Coding Standards" in content 276 - assert "Project Structure" in content 272 + # Should reference the coding skill, not inline dev guidelines 273 + assert "coding" in content.lower() 274 + assert "single source of truth" in content 275 + 276 + # The coding skill must exist with reference files 277 + coding_skill = Path(__file__).parent.parent / "muse" / "coding" / "SKILL.md" 278 + assert coding_skill.exists(), "muse/coding/SKILL.md not found" 279 + 280 + coding_refs = Path(__file__).parent.parent / "muse" / "coding" / "reference" 281 + assert (coding_refs / "coding-standards.md").exists() 282 + assert (coding_refs / "project-structure.md").exists() 283 + assert (coding_refs / "testing.md").exists() 284 + assert (coding_refs / "environment.md").exists()

Configure Feed

Configure Feed