@aquex/cmos-mcp 1.0.0

package/cmos-seed/db/schema.sql

@@ -0,0 +1,334 @@
+-- CMOS SQLite Schema
+-- Version: 2.1
+-- Generated for zero-dependency project initialization
+
+PRAGMA foreign_keys = ON;
+
+-- Project-level metadata
+-- Standard keys:
+--   project_id: UUID or slug uniquely identifying this CMOS project
+--   project_name: Human-readable project name
+--   tracelab_project_id: UUID of linked TraceLab project (for cross-referencing)
+--   created_at: ISO timestamp when project was initialized
+CREATE TABLE IF NOT EXISTS metadata (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+-- Initialize standard metadata keys (no-op if already exists)
+INSERT OR IGNORE INTO metadata (key, value) VALUES ('project_id', '');
+INSERT OR IGNORE INTO metadata (key, value) VALUES ('project_name', '');
+INSERT OR IGNORE INTO metadata (key, value) VALUES ('tracelab_project_id', '');
+INSERT OR IGNORE INTO metadata (key, value) VALUES ('created_at', datetime('now'));
+INSERT OR IGNORE INTO metadata (key, value) VALUES ('schema_version', '2.1');
+
+CREATE TABLE IF NOT EXISTS sprints (
+  id TEXT PRIMARY KEY,
+  title TEXT NOT NULL,
+  focus TEXT,
+  status TEXT,
+  start_date TEXT,
+  end_date TEXT,
+  total_missions INTEGER,
+  completed_missions INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS missions (
+  id TEXT PRIMARY KEY,
+  sprint_id TEXT REFERENCES sprints(id) ON DELETE SET NULL,
+  name TEXT NOT NULL,
+  status TEXT NOT NULL,
+  completed_at TEXT,
+  notes TEXT,
+
+  -- Full mission specification fields
+  objective TEXT,
+  context TEXT,
+  success_criteria TEXT,  -- JSON array
+  deliverables TEXT,      -- JSON array
+  reference_docs TEXT,    -- JSON array (renamed from 'references' to avoid SQL keyword)
+  domain_fields TEXT,     -- Full JSON of domainFields section
+
+  -- Timestamp fields for KPI calculations
+  created_at TEXT,        -- When mission was added
+  started_at TEXT,        -- When mission first moved to In Progress
+  updated_at TEXT,        -- Last state change timestamp
+
+  -- Legacy metadata field (for backward compatibility)
+  metadata TEXT
+);
+
+CREATE TABLE IF NOT EXISTS mission_dependencies (
+  from_id TEXT NOT NULL REFERENCES missions(id) ON DELETE CASCADE,
+  to_id TEXT NOT NULL REFERENCES missions(id) ON DELETE CASCADE,
+  type TEXT NOT NULL,
+  PRIMARY KEY (from_id, to_id)
+);
+
+CREATE TABLE IF NOT EXISTS contexts (
+  id TEXT PRIMARY KEY,
+  source_path TEXT NOT NULL,
+  content TEXT NOT NULL,
+  updated_at TEXT
+);
+
+CREATE TABLE IF NOT EXISTS context_snapshots (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  context_id TEXT NOT NULL,
+  session_id TEXT,
+  source TEXT,
+  content_hash TEXT NOT NULL,
+  content TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  FOREIGN KEY (context_id) REFERENCES contexts(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_context_snapshots_ctx ON context_snapshots (context_id, created_at);
+CREATE INDEX IF NOT EXISTS idx_context_snapshots_hash ON context_snapshots (context_id, content_hash);
+
+CREATE TABLE IF NOT EXISTS session_events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts TEXT,
+  agent TEXT,
+  mission TEXT,
+  action TEXT,
+  status TEXT,
+  summary TEXT,
+  next_hint TEXT,
+  raw_event TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS telemetry_events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  mission TEXT,
+  source_path TEXT NOT NULL,
+  ts TEXT,
+  payload TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS sessions (
+  id TEXT PRIMARY KEY,
+  type TEXT NOT NULL,
+  title TEXT NOT NULL,
+  sprint_id TEXT REFERENCES sprints(id) ON DELETE SET NULL,
+  started_at TEXT NOT NULL,
+  completed_at TEXT,
+  agent TEXT,
+  status TEXT NOT NULL DEFAULT 'active',
+  summary TEXT,
+  captures TEXT DEFAULT '[]',
+  next_steps TEXT,
+  metadata TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_sessions_type ON sessions (type);
+CREATE INDEX IF NOT EXISTS idx_sessions_status ON sessions (status);
+CREATE INDEX IF NOT EXISTS idx_sessions_started_at ON sessions (started_at DESC);
+
+CREATE TABLE IF NOT EXISTS prompt_mappings (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  prompt TEXT NOT NULL,
+  behavior TEXT NOT NULL
+);
+
+-- Strategic decisions index for queryable project memory
+-- Keeps decisions from MASTER_CONTEXT searchable without parsing JSON
+CREATE TABLE IF NOT EXISTS strategic_decisions (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  context_id TEXT NOT NULL DEFAULT 'master_context',
+  decision_text TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  sprint_id TEXT,
+  snapshot_id INTEGER,
+  project_domain TEXT,
+  session_id TEXT,  -- Reference to session where decision was captured
+  mission_id TEXT,  -- Reference to mission that produced this decision
+  source_chunk_ids TEXT,  -- JSON array of TraceLab chunk UUIDs for decision provenance
+  category TEXT,          -- architectural | process | tooling | design | business
+  superseded_by INTEGER,  -- FK to newer decision that replaces this one
+  status TEXT NOT NULL DEFAULT 'active',  -- active | superseded | archived
+  evidence TEXT,          -- JSON array of TraceLab evidence references [{type, id}]
+  content_hash TEXT,      -- SHA-256 hash for client-side dedup (decision_text + project_domain)
+  FOREIGN KEY (context_id) REFERENCES contexts(id) ON DELETE CASCADE,
+  FOREIGN KEY (sprint_id) REFERENCES sprints(id) ON DELETE SET NULL,
+  FOREIGN KEY (snapshot_id) REFERENCES context_snapshots(id) ON DELETE SET NULL,
+  FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE SET NULL,
+  FOREIGN KEY (mission_id) REFERENCES missions(id) ON DELETE SET NULL,
+  FOREIGN KEY (superseded_by) REFERENCES strategic_decisions(id) ON DELETE SET NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_strategic_decisions_created ON strategic_decisions (created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_strategic_decisions_sprint ON strategic_decisions (sprint_id);
+CREATE INDEX IF NOT EXISTS idx_strategic_decisions_domain ON strategic_decisions (project_domain);
+CREATE INDEX IF NOT EXISTS idx_strategic_decisions_session ON strategic_decisions (session_id);
+CREATE INDEX IF NOT EXISTS idx_strategic_decisions_mission ON strategic_decisions (mission_id);
+CREATE INDEX IF NOT EXISTS idx_strategic_decisions_status ON strategic_decisions (status);
+CREATE INDEX IF NOT EXISTS idx_strategic_decisions_category ON strategic_decisions (category);
+CREATE INDEX IF NOT EXISTS idx_strategic_decisions_hash ON strategic_decisions (content_hash);
+
+-- Structured learnings for queryable project knowledge
+CREATE TABLE IF NOT EXISTS learnings (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  content TEXT NOT NULL,
+  category TEXT,            -- technical | process | agent-behavior | tooling
+  status TEXT NOT NULL DEFAULT 'active',  -- active | archived | superseded
+  sprint_id TEXT,
+  session_id TEXT,
+  mission_id TEXT,
+  created_at TEXT NOT NULL,
+  content_hash TEXT,    -- SHA-256 hash for client-side dedup (content + category)
+  FOREIGN KEY (sprint_id) REFERENCES sprints(id) ON DELETE SET NULL,
+  FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE SET NULL,
+  FOREIGN KEY (mission_id) REFERENCES missions(id) ON DELETE SET NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_learnings_status ON learnings (status);
+CREATE INDEX IF NOT EXISTS idx_learnings_sprint ON learnings (sprint_id);
+CREATE INDEX IF NOT EXISTS idx_learnings_category ON learnings (category);
+CREATE INDEX IF NOT EXISTS idx_learnings_hash ON learnings (content_hash);
+
+-- FTS5 full-text search index for strategic decisions
+CREATE VIRTUAL TABLE IF NOT EXISTS decisions_fts USING fts5(
+  decision_text,
+  content='strategic_decisions',
+  content_rowid='id'
+);
+
+-- Auto-sync triggers for FTS5 index
+CREATE TRIGGER IF NOT EXISTS decisions_fts_insert AFTER INSERT ON strategic_decisions BEGIN
+  INSERT INTO decisions_fts(rowid, decision_text) VALUES (new.id, new.decision_text);
+END;
+
+CREATE TRIGGER IF NOT EXISTS decisions_fts_delete AFTER DELETE ON strategic_decisions BEGIN
+  INSERT INTO decisions_fts(decisions_fts, rowid, decision_text) VALUES('delete', old.id, old.decision_text);
+END;
+
+CREATE TRIGGER IF NOT EXISTS decisions_fts_update AFTER UPDATE OF decision_text ON strategic_decisions BEGIN
+  INSERT INTO decisions_fts(decisions_fts, rowid, decision_text) VALUES('delete', old.id, old.decision_text);
+  INSERT INTO decisions_fts(rowid, decision_text) VALUES (new.id, new.decision_text);
+END;
+
+-- Persistent sync event queue for WAL-backed event delivery
+-- Events are written here before HTTP push, surviving MCP restarts.
+CREATE TABLE IF NOT EXISTS sync_event_queue (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  event_type TEXT NOT NULL,
+  envelope TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending',
+  attempts INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL,
+  pushed_at TEXT,
+  last_error TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_sync_queue_status ON sync_event_queue (status, created_at);
+
+-- Session-mission association tracking
+-- Links sessions to missions via captures or explicit association
+CREATE TABLE IF NOT EXISTS session_missions (
+  session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  mission_id TEXT NOT NULL REFERENCES missions(id) ON DELETE CASCADE,
+  linked_at TEXT NOT NULL,
+  source TEXT NOT NULL DEFAULT 'capture',
+  PRIMARY KEY (session_id, mission_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_session_missions_mission ON session_missions (mission_id);
+
+-- Structured next-steps with lifecycle management
+-- Extracted from session completions, supports status tracking
+CREATE TABLE IF NOT EXISTS next_steps (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  content TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending',
+  session_id TEXT REFERENCES sessions(id) ON DELETE SET NULL,
+  sprint_id TEXT REFERENCES sprints(id) ON DELETE SET NULL,
+  mission_id TEXT REFERENCES missions(id) ON DELETE SET NULL,
+  created_at TEXT NOT NULL,
+  resolved_at TEXT,
+  carried_to_sprint TEXT REFERENCES sprints(id) ON DELETE SET NULL,
+  content_hash TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_next_steps_status ON next_steps (status);
+CREATE INDEX IF NOT EXISTS idx_next_steps_sprint ON next_steps (sprint_id);
+CREATE INDEX IF NOT EXISTS idx_next_steps_hash ON next_steps (content_hash);
+
+-- Structured constraints with lifecycle and expiry
+-- Extracted from session captures, supports staleness detection and archival
+CREATE TABLE IF NOT EXISTS constraints (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  content TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'active',
+  session_id TEXT REFERENCES sessions(id) ON DELETE SET NULL,
+  sprint_id TEXT REFERENCES sprints(id) ON DELETE SET NULL,
+  created_at TEXT NOT NULL,
+  expires_at TEXT,
+  archived_at TEXT,
+  content_hash TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_constraints_status ON constraints (status);
+CREATE INDEX IF NOT EXISTS idx_constraints_expires ON constraints (expires_at);
+CREATE INDEX IF NOT EXISTS idx_constraints_hash ON constraints (content_hash);
+
+-- Project identity view for easy access to project-level metadata
+CREATE VIEW IF NOT EXISTS project_identity AS
+SELECT
+  (SELECT value FROM metadata WHERE key = 'project_id') AS project_id,
+  (SELECT value FROM metadata WHERE key = 'project_name') AS project_name,
+  (SELECT value FROM metadata WHERE key = 'tracelab_project_id') AS tracelab_project_id,
+  (SELECT value FROM metadata WHERE key = 'created_at') AS created_at,
+  (SELECT value FROM metadata WHERE key = 'schema_version') AS schema_version;
+
+CREATE VIEW IF NOT EXISTS active_missions AS
+SELECT m.id,
+       m.name,
+       m.status,
+       m.completed_at,
+       m.notes,
+       s.id AS sprint_id,
+       s.title AS sprint_title
+  FROM missions m
+  LEFT JOIN sprints s ON s.id = m.sprint_id
+ WHERE m.status IN ('Current', 'In Progress');
+
+-- Mission detail view for easy inspection
+CREATE VIEW IF NOT EXISTS mission_details AS
+SELECT m.id,
+       m.name,
+       m.status,
+       s.id AS sprint_id,
+       s.title AS sprint_title,
+       m.objective,
+       m.context,
+       m.success_criteria,
+       m.deliverables,
+       m.reference_docs,
+       m.domain_fields,
+       m.completed_at,
+       m.notes
+  FROM missions m
+  LEFT JOIN sprints s ON s.id = m.sprint_id;
+
+-- Sprint summary view for retrospectives and analysis
+CREATE VIEW IF NOT EXISTS sprint_summary AS
+SELECT
+  s.id AS sprint_id,
+  s.title,
+  s.status,
+  s.focus,
+  s.start_date,
+  s.end_date,
+  COUNT(m.id) AS total_missions,
+  COUNT(CASE WHEN m.status = 'Completed' THEN 1 END) AS completed_missions,
+  COUNT(CASE WHEN m.status = 'Blocked' THEN 1 END) AS blocked_missions,
+  COUNT(CASE WHEN m.status IN ('Current', 'In Progress') THEN 1 END) AS active_missions,
+  (
+    SELECT COUNT(DISTINCT sd.id)
+    FROM strategic_decisions sd
+    WHERE sd.sprint_id = s.id
+  ) AS decisions_count
+FROM sprints s
+LEFT JOIN missions m ON m.sprint_id = s.id
+GROUP BY s.id, s.title, s.status, s.focus, s.start_date, s.end_date;

package/cmos-seed/docs/README.md

@@ -0,0 +1,128 @@
+# CMOS Documentation
+
+**Documentation for the Context + Mission Orchestration System (MCP-first architecture).**
+
+---
+
+## Quick Start
+
+**New to CMOS?** Start here:
+
+1. [Getting Started](./getting-started.md) - Quick setup guide
+2. [Build Session Prompt](./build-session-prompt.md) - Template for build sessions
+3. [Session Management Guide](./session-management-guide.md) - Planning, reviews, research
+
+---
+
+## Core Documentation
+
+| Document                                                  | Description                          |
+| --------------------------------------------------------- | ------------------------------------ |
+| [Getting Started](./getting-started.md)                   | Day 0 setup from fresh install       |
+| [Build Session Prompt](./build-session-prompt.md)         | Template for starting build sessions |
+| [Session Management Guide](./session-management-guide.md) | Planning, onboarding, reviews        |
+| [SQLite Schema Reference](./sqlite-schema-reference.md)   | Database structure and queries       |
+
+---
+
+## Documentation by Use Case
+
+### "I'm setting up CMOS for the first time"
+
+1. Read [Getting Started](./getting-started.md)
+2. Use `cmos_project_init()` to initialize
+
+### "I'm starting a build session"
+
+1. Use [Build Session Prompt](./build-session-prompt.md) as your template
+2. Follow: onboard → status → start → execute → complete
+
+### "I'm planning a sprint"
+
+1. Read [Session Management Guide](./session-management-guide.md)
+2. Use `cmos_session_start(type="planning")`
+
+### "I need database information"
+
+1. See [SQLite Schema Reference](./sqlite-schema-reference.md)
+2. Use `cmos_db_health()` for quick status
+
+---
+
+## Key Concepts
+
+### Sessions
+
+Non-build work: planning, onboarding, reviews. Managed via `cmos_session_*` tools.
+
+**Types:** planning, onboarding, review, research, check-in, custom
+
+### Missions
+
+Build work: implementing features, writing code. Managed via `cmos_mission_*` tools.
+
+**Lifecycle:** Queued → Current → In Progress → Completed (or Blocked)
+
+### Contexts
+
+- **project_context**: Current session state, working memory
+- **master_context**: Project history, decisions, constraints
+
+### Database
+
+SQLite at `cmos/db/cmos.sqlite` is source of truth. All operations via MCP tools.
+
+---
+
+## MCP Tools Quick Reference
+
+CMOS-MCP provides **27+ tools** for complete project management:
+
+```
+# Onboarding
+cmos_agent_onboard()                    # Get project state
+cmos_project_init()                     # Initialize new project
+
+# Missions
+cmos_mission_status()                   # View work queue
+cmos_mission_start(missionId="...")     # Begin mission
+cmos_mission_complete(missionId="...")  # Mark done
+cmos_mission_block(missionId="...")     # Block mission
+cmos_mission_unblock(missionId="...")   # Unblock mission
+cmos_mission_update(missionId="...")    # Update fields
+cmos_mission_add(...)                   # Create mission
+cmos_mission_depends(...)               # Add dependency
+
+# Sessions
+cmos_session_start(type="...", title="...")
+cmos_session_capture(category="...", content="...")
+cmos_session_complete(summary="...")
+cmos_session_list()                     # List sessions
+cmos_session_search(query="...")        # Search sessions
+
+# Sprints
+cmos_sprint_list()                      # List sprints
+cmos_sprint_show(sprintId="...")        # Sprint details
+cmos_sprint_add(...)                    # Create sprint
+cmos_sprint_update(...)                 # Update sprint
+
+# Context
+cmos_context_view()                     # View context
+cmos_context_snapshot(...)              # Create snapshot
+cmos_context_history()                  # View timeline
+cmos_context_update()                   # Aggregate sessions into context
+
+# Decisions
+cmos_decisions_list()                   # List decisions
+cmos_decisions_search(query="...")      # Search decisions
+
+# Health
+cmos_db_health()                        # Check database
+cmos_backlog_export()                   # Export backlog
+```
+
+---
+
+**Last Updated**: 2025-12-29
+**Schema Version**: 2.0 (MCP-first)
+**Tool Count**: 27+

package/cmos-seed/docs/agents-md-guide.md

@@ -0,0 +1,253 @@
+# Agent Configuration Guide
+
+**Purpose**: Understand how to configure AI agent instructions for CMOS-managed projects.
+
+---
+
+## Architecture Overview
+
+CMOS projects use **two layers** of AI configuration:
+
+### 1. Project Root agents.md (YOUR APPLICATION)
+
+**Location**: `project-root/agents.md`
+
+**Purpose**: Instructions for building YOUR APPLICATION CODE
+
+**Contains**:
+
+- Your project tech stack (React, FastAPI, etc.)
+- Your build commands (npm start, pytest, etc.)
+- Your coding standards and style guides
+- Your test requirements and coverage targets
+- Your deployment and CI/CD process
+- Your security requirements
+- Your API design patterns
+
+**Used when**: Agent is writing code in `src/`, `tests/`, `app/`, etc.
+
+**Example**:
+
+```markdown
+# AI Agent Configuration
+
+## Project Overview
+
+**Project Name**: TraceLab API
+**Primary Language**: Python
+**Framework**: FastAPI + PostgreSQL
+
+## Build Commands
+
+python -m uvicorn app.main:app --reload
+pytest tests/ -v
+
+## Coding Standards
+
+- Follow PEP 8
+- 80%+ test coverage required
+- Type hints on all functions
+```
+
+### 2. Tier Behavioral Guides (CMOS OPERATIONS)
+
+**Location**: `cmos/tiers/{tier}.md`
+
+**Purpose**: Behavioral guidance for how agents interact with CMOS tools
+
+**Available tiers**:
+
+| Tier        | File                    | Description                                        |
+| ----------- | ----------------------- | -------------------------------------------------- |
+| **Build**   | `cmos/tiers/build.md`   | Full mission/sprint workflow for structured builds |
+| **Managed** | `cmos/tiers/managed.md` | Mission tracking without sprint overhead           |
+| **General** | `cmos/tiers/general.md` | Lightweight — notes and decisions only             |
+
+**Tier selection**: Set via `cmos_project(action="update", projectType="general|managed|build")`.
+
+**Loaded automatically**: `cmos_agent_onboard()` reads the active tier config and adjusts the onboard payload accordingly — hiding irrelevant fields and filtering suggested actions.
+
+---
+
+## Critical Boundaries
+
+**When working on YOUR APPLICATION**:
+
+```
+Agent reads: project-root/agents.md
+Agent writes to: src/, tests/, docs/ (YOUR CODE)
+Agent ignores: cmos/ (management layer)
+```
+
+**When working on MISSIONS/PLANNING**:
+
+```
+Agent reads: cmos/tiers/{tier}.md (loaded automatically via onboard)
+Agent writes to: cmos/db/ (via MCP tools only)
+Agent ignores: src/ (application code)
+```
+
+**NEVER**:
+
+- Write application code in `cmos/`
+- Write application tests in `cmos/tests/` (those are CMOS tests)
+- Put mission management in project root
+
+---
+
+## Writing Effective agents.md (Project Root)
+
+### Structure
+
+Use this template structure:
+
+```markdown
+# AI Agent Configuration
+
+## Project Overview
+
+- Project name, type, tech stack
+- Brief description
+
+## Build & Development Commands
+
+- Installation
+- Development server
+- Build process
+- Testing
+
+## Project Structure & Navigation
+
+- Directory layout
+- Key files and their purposes
+
+## Coding Standards & Style
+
+- Language-specific guidelines
+- Naming conventions
+- Code organization patterns
+
+## Testing Preferences
+
+- Framework to use
+- Coverage requirements
+- Test structure
+
+## Security & Quality Guardrails
+
+- Security rules
+- Code review requirements
+- Quality gates
+
+## Architecture Patterns
+
+- Preferred design patterns
+- Integration approaches
+
+## Project-Specific Configuration
+
+- Environment variables
+- External services
+- Special requirements
+```
+
+### Best Practices
+
+**Be Specific**:
+
+```markdown
+Bad: "Write good tests"
+Good: "Use pytest with fixtures. Minimum 80% coverage. Test file naming: test\_\*.py"
+```
+
+**Give Examples**:
+
+```markdown
+## API Design
+
+All endpoints return JSON:
+{
+"data": {...},
+"meta": {"timestamp": "...", "version": "..."}
+}
+```
+
+**State Constraints**:
+
+```markdown
+## Security Rules
+
+- Never commit API keys
+- Use environment variables for secrets
+- All database queries must use parameterized statements
+```
+
+**Define Success**:
+
+```markdown
+## Testing Requirements
+
+- All features need integration tests
+- Critical paths need E2E tests
+- Run full suite before marking mission complete
+```
+
+---
+
+## Tier Configuration
+
+Each tier file uses YAML frontmatter to declare its behavioral surface:
+
+```yaml
+---
+tier: build
+label: Build
+tools_use: [cmos_mission, cmos_sprint, cmos_session, ...]
+tools_skip: []
+vocabulary:
+  task: mission
+  note: decision
+onboard_fields_show: [currentSprint, pendingMissions, blockedMissions]
+onboard_fields_hide: []
+---
+```
+
+The markdown body below the frontmatter provides the behavioral guide text that gets included in onboard output.
+
+### Choosing a Tier
+
+- **Build** (default): Full CMOS workflow with sprints, missions, sessions, and decisions. Best for structured engineering projects.
+- **Managed**: Mission tracking without sprint overhead. Good for ongoing work without sprint cadence.
+- **General**: Lightweight note-taking and decision capture. Best for exploration, research, or projects that don't need mission tracking.
+
+---
+
+## Directory Structure
+
+```
+project/
+├── agents.md              # YOUR APPLICATION instructions
+└── cmos/
+    ├── db/
+    │   └── cmos.sqlite    # All CMOS state
+    ├── tiers/             # Tier behavioral guides
+    │   ├── build.md
+    │   ├── general.md
+    │   └── managed.md
+    └── docs/              # Optional documentation
+```
+
+---
+
+## Quick Start Summary
+
+1. **Project root agents.md** — Instructions for YOUR CODE
+2. **Tier guides in cmos/tiers/** — CMOS behavioral configuration (loaded automatically)
+3. **Clear boundaries** — Never mix application and management concerns
+4. **Be specific** — Give real commands and examples in agents.md
+5. **Keep updated** — Evolve agents.md with your project
+
+---
+
+**Last Updated**: 2026-03-13
+**See Also**: `cmos/docs/getting-started.md` for full setup flow