@aquex/cmos-mcp 1.0.0

package/cmos-seed/docs/build-session-prompt.md

@@ -0,0 +1,137 @@
+# Build Session Prompt
+
+**Purpose**: Efficient prompt for running multiple build missions in a session loop.
+
+**Usage**: Paste at the start of a build session to establish context.
+
+---
+
+## Session Initialization Prompt
+
+```
+We're running a CMOS build session. If anything is unclear, pause and ask before proceeding.
+
+CMOS uses MCP tools for database operations. Start by getting context:
+
+1. ONBOARD: Call cmos_agent_onboard() to get project state
+   - Verify project identity (project_id, project_name)
+   - Check you're working on the correct project database
+2. HEALTH CHECK: Call cmos_db_health() to verify database
+3. LOAD RULES: Read cmos/tiers/build.md for project rules
+
+Then run missions in a loop:
+
+1. SELECT NEXT: Call cmos_mission_status() to see work queue
+   - Priority: In Progress → Current → Queued
+
+2. START: Call cmos_mission_start(missionId="<id>")
+   - Logs start event to database
+   - Transitions to In Progress
+
+3. EXECUTE: Actually implement the work
+   - Write real code, not stubs
+   - Create comprehensive tests
+   - Verify all success criteria met
+   - CRITICAL: Don't mark complete unless work is actually done
+
+4. COMPLETE: Call cmos_mission_complete(missionId="<id>", notes="<what was done>")
+   - Marks completed in database
+   - Logs completion event
+
+5. VERIFY: Call cmos_mission_status() to confirm state
+
+If blocked: Call cmos_mission_block(missionId="<id>", reason="<why>", blockers=["<what's needed>"])
+
+Loop until all missions complete or you need to pause.
+```
+
+---
+
+## Minimal Loop Prompt
+
+```
+CMOS build loop:
+
+1. Status: cmos_mission_status()
+2. Start: cmos_mission_start(missionId="...")
+3. Execute: Implement fully, test thoroughly
+4. Complete: cmos_mission_complete(missionId="...", notes="...")
+5. Repeat
+```
+
+---
+
+## Key Principles
+
+**Database First**:
+
+- SQLite is source of truth
+- All state managed via MCP tools
+- No file mirrors to maintain
+
+**Validation Checkpoints**:
+
+- After each mission completion
+- Before ending session
+- If anything seems wrong
+
+**Mission Loop Efficiency**:
+
+- Don't re-explain system between missions
+- Trust tools to handle transitions
+- Focus on execution and validation
+
+---
+
+## Common Session Patterns
+
+### Pattern 1: Sequential Execution
+
+Run missions one by one until backlog clears.
+
+### Pattern 2: Batch Similar Missions
+
+Group related missions and run together.
+
+### Pattern 3: Stop on Blocker
+
+If mission blocks, document needs, end session.
+
+---
+
+## Example Session Flow
+
+```
+You: [Paste Session Initialization Prompt]
+
+Agent: Loaded. Running cmos_agent_onboard()... Found next mission: s16-m01
+
+You: Go ahead
+
+Agent: [Starts, implements, tests, completes, validates]
+       Next mission: s16-m02. Ready to start?
+
+You: Yes
+
+Agent: [Starts, implements, tests, completes, validates]
+       Next mission: s16-m03. Ready?
+
+You: Pause there, let's review
+```
+
+---
+
+## Project Identity Validation
+
+The onboard response includes project identity:
+
+- `project.id` - Unique project identifier
+- `project.name` - Human-readable project name
+- `project.tracelabProjectId` - Linked TraceLab project (if any)
+
+**Verify you're working on the correct project** before executing missions. If the project identity doesn't match your expectations, you may have the wrong database.
+
+---
+
+**Last Updated**: 2025-12-29
+**For**: Build session mission loops

package/cmos-seed/docs/getting-started.md

@@ -0,0 +1,150 @@
+# Getting Started with CMOS
+
+**Day 0 Setup**: From fresh project to CMOS-enabled in minutes.
+
+---
+
+## What is CMOS?
+
+**CMOS** (Context + Mission Orchestration System) is a project management layer for AI-assisted development. It provides:
+
+- **SQLite-backed mission tracking** - History, sprints, dependencies
+- **Context management** - PROJECT_CONTEXT, MASTER_CONTEXT with snapshots
+- **Mission-based workflow** - Research → Plan → Build → Ship
+- **Session management** - Capture planning, onboarding, reviews
+- **MCP integration** - All operations via MCP tools, no CLI required
+
+**Critical Principle**: CMOS is **project management**, NOT your application code.
+
+---
+
+## Quick Start
+
+### 1. Initialize with cmos_project_init
+
+```
+cmos_project_init({
+  projectRoot: "/path/to/your/project",
+  projectName: "My Project",
+  initialSprint: {
+    id: "sprint-01",
+    title: "Initial Sprint"
+  }
+})
+```
+
+This creates:
+
+```
+yourproject/
+└── cmos/
+    ├── db/
+    │   └── cmos.sqlite  # All CMOS state
+    ├── tiers/           # Tier behavioral guides
+    └── docs/            # Documentation (optional)
+```
+
+### 2. Onboard
+
+```
+cmos_agent_onboard()
+```
+
+Get project state, pending missions, and recent decisions.
+
+### 3. Start Working
+
+```
+cmos_mission_status()  # See work queue
+cmos_mission_start(missionId="s01-m01")  # Begin work
+```
+
+---
+
+## Project Structure
+
+```
+yourproject/                    # Project root
+├── README.md                   # About YOUR PROJECT
+├── agents.md                   # AI instructions for YOUR CODE (optional)
+│
+├── src/                        # YOUR APPLICATION CODE
+├── tests/                      # YOUR APPLICATION TESTS
+│
+└── cmos/                       # PROJECT MANAGEMENT (separate!)
+    ├── db/
+    │   └── cmos.sqlite         # Mission tracking database
+    ├── tiers/                  # Tier behavioral guides (general/managed/build)
+    └── docs/                   # CMOS documentation
+```
+
+**Golden Rule**:
+
+- Write YOUR CODE in project root
+- Manage YOUR WORK in cmos/
+- NEVER write application code in cmos/
+
+---
+
+## Core MCP Tools
+
+| Tool                    | Purpose                                        |
+| ----------------------- | ---------------------------------------------- |
+| `cmos_project_init`     | Initialize new CMOS project                    |
+| `cmos_agent_onboard`    | Get project context for cold-start             |
+| `cmos_db_health`        | Check database status                          |
+| `cmos_mission_status`   | View work queue                                |
+| `cmos_mission_start`    | Begin mission                                  |
+| `cmos_mission_complete` | Mark mission done                              |
+| `cmos_session_start`    | Start planning session                         |
+| `cmos_session_capture`  | Record decisions                               |
+| `cmos_session_complete` | Complete session                               |
+| `cmos_context_update`   | Aggregate session insights into master_context |
+| `cmos_context_view`     | View project or master context                 |
+
+---
+
+## Build Session Workflow
+
+1. **Onboard**: `cmos_agent_onboard()`
+2. **Check Queue**: `cmos_mission_status()`
+3. **Start Mission**: `cmos_mission_start(missionId="...")`
+4. **Execute Work**: Write code, create tests
+5. **Complete**: `cmos_mission_complete(missionId="...", notes="...")`
+6. **Repeat**: Continue with next mission
+
+---
+
+## Session Workflow
+
+For planning, research, or review (not mission execution):
+
+1. **Start**: `cmos_session_start(type="planning", title="Sprint Planning")`
+2. **Capture**: `cmos_session_capture(category="decision", content="...")`
+3. **Complete**: `cmos_session_complete(summary="...")`
+
+---
+
+## Keeping Context Fresh
+
+After multiple sessions, aggregate captured decisions and learnings into master_context:
+
+```
+cmos_context_update()
+```
+
+This keeps your project's strategic memory up-to-date. Run periodically or at sprint boundaries.
+
+---
+
+## Next Steps
+
+1. Run `cmos_agent_onboard()` to see project state
+2. Run `cmos_mission_status()` to see work queue
+3. Start your first mission with `cmos_mission_start()`
+4. See `cmos/tiers/build.md` for build session behavioral guide
+
+---
+
+**Last Updated**: 2025-12-29
+**Schema Version**: 2.0

package/cmos-seed/docs/session-management-guide.md

@@ -0,0 +1,163 @@
+# Session Management Guide
+
+Sessions capture planning, onboarding, research, and review activities that fall outside mission-oriented build work.
+
+---
+
+## Session Types
+
+| Type       | Use Case                                         |
+| ---------- | ------------------------------------------------ |
+| onboarding | Ramp up a new agent or hand off a feature        |
+| planning   | Sprint, roadmap, or architecture planning        |
+| review     | Weekly reviews, retrospectives, evaluations      |
+| research   | Exploratory spikes, benchmarking, investigations |
+| check-in   | Quick syncs to capture status and blockers       |
+| custom     | Any structured collaboration needing a record    |
+
+All types share the same lifecycle: **start → capture → complete**.
+
+---
+
+## Basic Workflow
+
+### 1. Start a Session
+
+```
+cmos_session_start({
+  type: "planning",
+  title: "Sprint 17 Planning",
+  sprintId: "sprint-17"  // optional
+})
+```
+
+### 2. Capture Insights (repeat as needed)
+
+```
+cmos_session_capture({
+  category: "decision",
+  content: "Focus on API performance"
+})
+
+cmos_session_capture({
+  category: "constraint",
+  content: "Must maintain backward compatibility"
+})
+
+cmos_session_capture({
+  category: "next-step",
+  content: "Profile current latency"
+})
+```
+
+**Categories**: `decision`, `learning`, `constraint`, `context`, `next-step`
+
+### 3. Complete the Session
+
+```
+cmos_session_complete({
+  summary: "Sprint 17 scoped and prioritized",
+  nextSteps: ["Finalize API metrics", "Update backlog"]
+})
+```
+
+---
+
+## Worked Examples
+
+### Sprint Planning
+
+```
+cmos_session_start(type="planning", title="Sprint 17 Planning")
+
+cmos_session_capture(category="decision", content="Focus on API performance")
+cmos_session_capture(category="constraint", content="Backward compatibility required")
+cmos_session_capture(category="next-step", content="Profile API endpoints")
+
+cmos_session_complete(summary="Sprint 17 planned: 6 missions for API optimization")
+```
+
+### Agent Onboarding
+
+```
+cmos_session_start(type="onboarding", title="Onboarding for Feature X")
+
+cmos_session_capture(category="context", content="Feature X requires real-time updates")
+cmos_session_capture(category="decision", content="Use WebSockets for real-time")
+
+cmos_session_complete(
+  summary="Onboarded to Feature X implementation",
+  nextSteps=["Review WebSocket libraries", "Design message protocol"]
+)
+```
+
+### Weekly Review
+
+```
+cmos_session_start(type="review", title="Week 47 Review")
+
+cmos_session_capture(category="learning", content="CI/CD pipeline needs optimization")
+cmos_session_capture(category="learning", content="Velocity improved with pair programming")
+
+cmos_session_complete(summary="Week 47: Good progress, CI/CD needs work")
+```
+
+---
+
+## Viewing Sessions
+
+```
+cmos_session_list()                    // List all sessions
+cmos_session_list(status="completed")  // Filter by status
+cmos_session_list(type="planning")     // Filter by type
+```
+
+---
+
+## Tips
+
+- Keep captures concise (<1000 chars)
+- Use next-steps to seed future missions
+- Complete sessions before starting new ones
+- Use `cmos_agent_onboard()` to see active sessions
+
+---
+
+## Keeping Context Fresh
+
+After completing sessions, decisions and learnings are stored in the database. To aggregate recent session captures into `master_context` for strategic memory:
+
+```
+cmos_context_update()
+```
+
+This tool:
+
+- Scans completed sessions since last context update
+- Extracts decisions, learnings, and constraints
+- Updates master_context with aggregated insights
+- Creates automatic snapshot for history
+
+**When to use**:
+
+- After completing multiple planning sessions
+- At sprint boundaries
+- Before onboarding a new agent
+- When master_context feels stale
+
+**Workflow Example**:
+
+```
+# Complete several planning sessions
+cmos_session_complete(summary="Sprint planning complete")
+
+# Later, aggregate insights into master_context
+cmos_context_update()
+
+# View updated context
+cmos_context_view(contextType="master_context")
+```
+
+---
+
+**Last Updated**: 2025-12-29

package/cmos-seed/docs/sqlite-schema-reference.md

@@ -0,0 +1,188 @@
+# SQLite Schema Reference
+
+**Database**: `cmos/db/cmos.sqlite`  
+**Schema**: `cmos/db/schema.sql`
+
+Quick reference for querying CMOS history using any SQLite client.
+
+---
+
+## Core Tables
+
+| Table                  | Purpose                                  | Key Columns                                                     |
+| ---------------------- | ---------------------------------------- | --------------------------------------------------------------- |
+| `sprints`              | Sprint registry with metrics             | `id`, `title`, `status`, `total_missions`, `completed_missions` |
+| `missions`             | Mission backlog with status              | `id`, `sprint_id`, `name`, `status`, `completed_at`, `notes`    |
+| `mission_dependencies` | Edges between missions                   | `from_id`, `to_id`, `type`                                      |
+| `contexts`             | JSON payloads for PROJECT/MASTER context | `id`, `content`, `updated_at`                                   |
+| `context_snapshots`    | Historical context versions              | `context_id`, `content`, `created_at`, `content_hash`           |
+| `sessions`             | Universal session registry               | `id`, `type`, `sprint_id`, `started_at`, `status`               |
+| `session_events`       | Append-only session log                  | `ts`, `agent`, `mission`, `action`, `status`, `summary`         |
+| `telemetry_events`     | Runtime metrics and health signals       | `source_path`, `event_data`, `created_at`                       |
+| `prompt_mappings`      | Prompt → behavior mapping                | `prompt`, `behavior`                                            |
+
+**Views**:
+
+- `active_missions` - Convenience projection for current work
+
+---
+
+## Useful Queries
+
+### View Current Sprint Status
+
+```sql
+SELECT sprint_id, status, COUNT(*) as count
+FROM missions
+GROUP BY sprint_id, status
+ORDER BY sprint_id, status;
+```
+
+### Find Active/Recent Missions
+
+```sql
+SELECT id, name, status, completed_at
+FROM missions
+WHERE status IN ('Current', 'In Progress', 'Queued')
+ORDER BY completed_at DESC NULLS FIRST;
+```
+
+### View Sprint Progress
+
+```sql
+SELECT id, title,
+       completed_missions || '/' || total_missions as progress,
+       status
+FROM sprints
+ORDER BY id;
+```
+
+### Get Recent Sessions
+
+```sql
+SELECT ts, mission, action, status, summary
+FROM session_events
+ORDER BY ts DESC
+LIMIT 10;
+```
+
+### Review Planning/Onboarding Sessions
+
+```sql
+SELECT id, type, title, started_at, completed_at, status
+FROM sessions
+WHERE type IN ('planning', 'onboarding')
+ORDER BY started_at DESC
+LIMIT 10;
+```
+
+### Export Full Mission History for a Sprint
+
+```sql
+SELECT id, name, status, completed_at, notes
+FROM missions
+WHERE sprint_id = 'Sprint 05'
+ORDER BY id;
+```
+
+### Check Context Updates
+
+```sql
+SELECT id, updated_at,
+       LENGTH(content) as size_bytes
+FROM contexts
+ORDER BY updated_at DESC;
+```
+
+### View Context History
+
+```sql
+SELECT created_at, session_id, source,
+       LENGTH(content) as size_bytes
+FROM context_snapshots
+WHERE context_id = 'master_context'
+ORDER BY created_at DESC
+LIMIT 5;
+```
+
+---
+
+## Accessing the Database
+
+Use any SQLite client:
+
+**Command line**:
+
+```bash
+sqlite3 cmos/db/cmos.sqlite
+
+# Run query
+sqlite3 cmos/db/cmos.sqlite "SELECT * FROM sprints;"
+
+# Interactive mode
+sqlite3 cmos/db/cmos.sqlite
+> .tables
+> .schema missions
+> SELECT * FROM missions LIMIT 5;
+```
+
+**GUI tools** (any will work):
+
+- DB Browser for SQLite
+- DBeaver
+- TablePlus
+- DataGrip
+- VS Code SQLite extension
+- etc.
+
+All standard SQLite tools work - no special configuration needed.
+
+---
+
+## Schema Details
+
+See `cmos/db/schema.sql` for complete schema including:
+
+- Table definitions with foreign keys
+- Indexes for query performance
+- Views for common queries
+- Constraints and defaults
+
+---
+
+## Maintenance Queries
+
+### Compact Database
+
+```sql
+VACUUM;
+```
+
+### Check Database Size
+
+```sql
+SELECT page_count * page_size as size_bytes
+FROM pragma_page_count(), pragma_page_size();
+```
+
+### Verify Foreign Keys
+
+```sql
+PRAGMA foreign_key_check;
+```
+
+### List All Tables and Row Counts
+
+```sql
+SELECT name,
+       (SELECT COUNT(*) FROM sqlite_master m2
+        WHERE m2.type='table' AND m2.name=m1.name)
+FROM sqlite_master m1
+WHERE type='table'
+ORDER BY name;
+```
+
+---
+
+**Last Updated**: 2025-11-13  
+**Replaces**: `sqlite-db-browser-guide.md` (tool-agnostic version)