@aquex/cmos-mcp 1.0.0

package/cmos-seed/templates/PROJECT-README-template.md

@@ -0,0 +1,110 @@
+# [Your Project Name]
+
+**Status**: [In Development / Beta / Production]  
+**Managed with**: CMOS (Context + Mission Orchestration System)
+
+[Brief 2-3 sentence description of what your project does and why it exists]
+
+---
+
+## Quick Start
+
+```bash
+# Install dependencies
+[your install command]
+
+# Setup environment
+[your setup commands]
+
+# Run development server
+[your dev command]
+
+# Run tests
+[your test command]
+```
+
+---
+
+## Project Documentation
+
+- **Roadmap**: See `docs/roadmap.md` for project vision and sprint plan
+- **Technical Architecture**: See `docs/technical_architecture.md` for system design
+- **API Documentation**: [Link to your API docs if applicable]
+
+---
+
+## Development
+
+### Prerequisites
+- [Language] [version]
+- [Database] [version]
+- [Other dependencies]
+
+### Environment Setup
+```bash
+# [Step-by-step setup instructions]
+```
+
+### Running Tests
+```bash
+# [Your test commands]
+```
+
+### Building for Production
+```bash
+# [Your build commands]
+```
+
+---
+
+## Project Management with CMOS
+
+This project uses CMOS for mission-based development workflow.
+
+**For contributors**:
+- Mission tracking: See `cmos/missions/backlog.yaml`
+- Project history: Stored in `cmos/db/cmos.sqlite`
+- Session logs: See `cmos/SESSIONS.jsonl`
+
+**For AI agents**:
+- Application code guidance: See `agents.md` (this project root)
+- CMOS operations guidance: See `cmos/tiers/build.md`
+- Build session prompts: See `cmos/docs/build-session-prompt.md`
+
+**CMOS commands** (from project root):
+```bash
+# View current mission status
+./cmos/cli.py db show current
+
+# View sprint progress
+./cmos/cli.py db show backlog
+
+# Validate system integrity
+./cmos/cli.py validate health
+```
+
+---
+
+## Contributing
+
+[Your contribution guidelines]
+
+---
+
+## License
+
+[Your license]
+
+---
+
+## CMOS Directory
+
+The `cmos/` directory contains project management infrastructure:
+- Mission and sprint tracking
+- Context and session history
+- Planning and orchestration scripts
+
+**Do not write application code in `cmos/`** - it's for project management only.
+
+See `cmos/README.md` for CMOS-specific documentation.
+

package/cmos-seed/templates/agents.md

@@ -0,0 +1,306 @@
+# AI Agent Configuration
+
+**Instructions**: Copy this file to your project root and customize for YOUR project.
+
+**Location**: This file should live at `project-root/agents.md` (NOT in cmos/)
+
+**Purpose**: Guide AI agents when building YOUR APPLICATION CODE.
+
+---
+
+## Project Overview
+**Project Name**: [Your Project Name]  
+**Project Type**: [Web API, Web App, CLI Tool, Library, etc.]  
+**Primary Language**: [Python, TypeScript, JavaScript, Go, etc.]  
+**Framework**: [FastAPI, React, Next.js, Express, etc.]
+
+**Description**: [Brief 1-2 sentence description of what you're building]
+
+---
+
+## Build & Development Commands
+
+### Installation & Setup
+```bash
+# Install dependencies
+[your install command]
+
+# Setup database/environment
+[your setup commands]
+
+# First-time setup
+[any initialization needed]
+```
+
+### Development
+```bash
+# Start development server
+[your dev command]
+
+# Watch mode (if applicable)
+[your watch command]
+```
+
+### Building
+```bash
+# Build for production
+[your build command]
+
+# Build for staging (if applicable)
+[your staging build]
+```
+
+### Testing
+```bash
+# Run all tests
+[your test command]
+
+# Run unit tests
+[your unit test command]
+
+# Run integration tests
+[your integration test command]
+
+# Generate coverage
+[your coverage command]
+```
+
+### Linting & Formatting
+```bash
+# Lint code
+[your lint command]
+
+# Format code
+[your format command]
+
+# Type checking (if applicable)
+[your type check command]
+```
+
+---
+
+## Project Structure & Navigation
+
+### Directory Layout
+```
+project-root/
+├── [your source directory]/      # Application code
+├── tests/                         # Application tests
+├── docs/                          # Project documentation
+├── [config directory]/            # Configuration files
+├── [scripts directory]/           # Build and utility scripts
+└── cmos/                          # Project management (DO NOT write code here!)
+```
+
+### Key Files
+- `[main entry point]` - [description]
+- `[config file]` - [description]
+- `[important files]` - [description]
+
+**Critical**: Never write application code in `cmos/` directory. That's for project management only.
+
+---
+
+## Coding Standards & Style
+
+### [Language] Guidelines
+- [Specific coding standards for your primary language]
+- [Naming conventions]
+- [Code organization patterns]
+- [Formatting rules]
+
+**Examples**:
+```[language]
+// Show an example of your preferred style
+```
+
+### File Organization
+- [How files should be organized]
+- [Naming conventions for files]
+- [Module/package structure]
+
+### Comments & Documentation
+- [When to write comments]
+- [Documentation string requirements]
+- [Inline documentation style]
+
+---
+
+## Testing Preferences
+
+### Framework & Tools
+- **Framework**: [pytest, Jest, Mocha, etc.]
+- **Coverage target**: [80%, 90%, etc.]
+- **Coverage tool**: [pytest-cov, Istanbul, etc.]
+
+### Test Structure
+- **Test location**: `tests/` directory (NOT in cmos/)
+- **Test naming**: [test_*.py, *.test.js, etc.]
+- **Test organization**: [by feature, by module, etc.]
+
+### Testing Requirements
+- [ ] [Specific requirement 1]
+- [ ] [Specific requirement 2]
+- [ ] All features must have tests
+- [ ] Critical paths need integration tests
+- [ ] Run full suite before marking missions complete
+
+**Example test**:
+```[language]
+// Show an example test in your preferred style
+```
+
+---
+
+## Security & Quality Guardrails
+
+### Security Rules
+- Never commit API keys or secrets
+- Use environment variables for sensitive data
+- [Your specific security requirements]
+- [Authentication/authorization patterns]
+- [Data protection requirements]
+
+### Code Quality Gates
+- [Linting must pass]
+- [Type checking must pass (if applicable)]
+- [Coverage must meet threshold]
+- [Code review requirements]
+
+### Forbidden Patterns
+- ❌ [Pattern 1 you want to avoid]
+- ❌ [Pattern 2 you want to avoid]
+- ❌ Hardcoded credentials
+- ❌ Raw SQL queries (use ORM/query builder)
+
+---
+
+## Architecture Patterns
+
+### Preferred Design Patterns
+- **[Pattern 1]**: [When and how to use it]
+- **[Pattern 2]**: [When and how to use it]
+
+**Examples**:
+```[language]
+// Show example implementation of preferred pattern
+```
+
+### Database Access
+- **ORM/Tool**: [SQLAlchemy, Prisma, TypeORM, etc.]
+- **Migration tool**: [Alembic, Knex, Prisma, etc.]
+- **Connection pattern**: [Connection pooling, etc.]
+
+### API Design (if applicable)
+- **Style**: [REST, GraphQL, gRPC, etc.]
+- **Response format**: [JSON structure, error format, etc.]
+- **Authentication**: [JWT, OAuth, API keys, etc.]
+
+---
+
+## Project-Specific Configuration
+
+### Environment Variables
+```bash
+# Development
+[YOUR_ENV_VAR]=value
+[ANOTHER_VAR]=value
+
+# Production
+[PROD_VARS]=value
+```
+
+### External Services
+- **[Service 1]**: [Purpose and configuration]
+- **[Service 2]**: [Purpose and configuration]
+
+### Deployment
+- **Platform**: [Vercel, Railway, AWS, etc.]
+- **Process**: [Deployment steps or CI/CD info]
+- **Environment**: [Staging, production setup]
+
+---
+
+## CMOS Integration Notes
+
+### When Working on Application Code
+1. Read THIS agents.md (project-root/agents.md)
+2. Write code to `src/`, `app/`, or your source directory
+3. Write tests to `tests/` directory
+4. Never write application code to `cmos/`
+
+### When Working on CMOS Operations
+1. Read `cmos/tiers/build.md` for CMOS-specific instructions
+2. Use mission runtime scripts
+3. Update missions and contexts in `cmos/`
+4. Keep application code and CMOS management separate
+
+### Before Completing Missions
+- [ ] All application tests pass
+- [ ] Code meets standards defined above
+- [ ] Documentation updated if needed
+- [ ] Mission status verified in database
+
+---
+
+## Development Workflow
+
+### Branch Strategy (if using Git)
+- **Main**: [Your main branch strategy]
+- **Development**: [Your dev branch strategy]
+- **Features**: [Your feature branch naming]
+
+### Commit Messages
+```
+[type]([scope]): [description]
+
+Examples:
+feat(api): add user authentication endpoint
+fix(db): resolve connection pool timeout
+docs(readme): update installation instructions
+test(auth): add integration tests for OAuth
+```
+
+---
+
+## Notes for AI Agents
+
+### Context Loading Priority
+1. Load `project-root/agents.md` (THIS FILE) for application work
+2. Load `cmos/tiers/build.md` for CMOS operations
+3. Load `cmos/PROJECT_CONTEXT.json` for current state
+4. Load `cmos/context/MASTER_CONTEXT.json` for project history
+5. Reference `cmos/SESSIONS.jsonl` for recent session history
+
+### Output Standards
+- Use [Markdown, reStructuredText, etc.] for documentation
+- Use [your preferred format] for reports
+- Include code examples with syntax highlighting
+- Keep explanations [concise/detailed/etc.]
+
+### Communication Style
+- [Your preference: concise, detailed, technical, etc.]
+- [How to present options]
+- [When to ask clarifying questions]
+
+---
+
+## Customization Checklist
+
+Before using this template, update:
+
+- [ ] All `[bracketed placeholders]` with your actual values
+- [ ] Project overview with real project details
+- [ ] Build commands with your actual commands
+- [ ] Project structure with your actual directories
+- [ ] Coding standards with your actual rules
+- [ ] Testing requirements with your actual framework
+- [ ] Security rules with your specific requirements
+- [ ] Remove this checklist section when done
+
+---
+
+**Template Version**: 2.0  
+**Last Updated**: 2025-11-08  
+**Copy to**: `project-root/agents.md` (NOT cmos/)  
+**Customize**: Replace all [placeholders] with your project details

package/cmos-seed/tiers/build.md

@@ -0,0 +1,110 @@
+---
+tier: build
+label: Build
+description: Full structured engineering project management with sprints, missions, and formal decision tracking.
+tools_use:
+  - cmos_agent_onboard
+  - cmos_session
+  - cmos_context
+  - cmos_decisions
+  - cmos_learnings
+  - cmos_mission
+  - cmos_mission_transition
+  - cmos_sprint
+  - cmos_db
+  - cmos_message
+  - cmos_project
+tools_skip: []
+vocabulary:
+  task: mission
+  task_group: sprint
+  start_work: start mission
+  finish_work: complete mission
+  plan: sprint planning
+  review: sprint review / retro
+  checkpoint: sprint completion
+  note: decision
+  action_item: next-step
+  progress_check: mission status
+  time_box: sprint
+  blocker: blocked mission
+session_types: [planning, review, research, check-in, onboarding, custom]
+onboard_fields_show: [currentSprint, pendingMissions, blockedMissions, syncHealth]
+graduation_from: managed
+---
+
+# Build Tier — Agent Behavioral Guide
+
+You are a structured engineering project manager. You run the full CMOS build loop with formal sprints, missions, and decision tracking. Every action is traceable. Every decision is captured. The work follows a disciplined cycle: plan, execute, verify, review.
+
+## Session Loop
+
+1. **Onboard.** Call `cmos_agent_onboard` at the start of every conversation. Read the full payload — sprint context, pending missions, blocked work, unread messages, sync health. Act on warnings.
+
+2. **Select next mission.** Call `cmos_mission(action="status")`. Priority order: In Progress > Current > Queued. If a mission is blocked, address the blocker before moving on.
+
+3. **Start mission.** Call `cmos_mission_transition(action="start", missionId="...")`. Review the relevant decisions surfaced automatically via FTS5. Understand the objective and success criteria before writing code.
+
+4. **Execute.** Implement production code, tests, and documentation. Avoid placeholders and stubs. Write real, working code. Run the test suite. Fix what you break.
+
+5. **Complete mission.** Call `cmos_mission_transition(action="complete", missionId="...", notes="...", decisions=[...])`. Include every strategic decision made during the mission. Notes should describe what was actually done, not what was planned.
+
+6. **Verify.** Call `cmos_mission(action="status")` to confirm queue state. Check that tests pass, build succeeds, lint is clean.
+
+7. **If blocked.** Call `cmos_mission_transition(action="block", missionId="...", reason="...", blockers=[...])`. Be specific about what's needed to unblock.
+
+## Sprint Lifecycle
+
+- **Planning.** Start each sprint with a planning session. Define missions with clear objectives, success criteria, and deliverables. Set mission dependencies where they exist.
+- **Execution.** Work through the mission queue in order. Capture decisions as you make them. Complete missions with thorough notes.
+- **Review.** At sprint end, run a review session. Capture learnings (what worked, what didn't). Generate a retrospective with `cmos_sprint(action="retro")`.
+- **Completion.** Close the sprint with `cmos_sprint(action="complete", summary="...")`. This triggers decision archival, context snapshots, and checkpoint backfill to the dashboard.
+
+## Session Types
+
+Use structured session types deliberately:
+
+- `planning` — Sprint or mission planning. Produces tasks, decisions, and priorities.
+- `review` — Sprint reviews and retrospectives. Captures learnings and carry-forward items.
+- `research` — Investigation before implementation. Produces context and constraints.
+- `check-in` — Quick status alignment. Lightweight, minimal captures.
+- `onboarding` — First session in a new context. Orients the agent.
+
+## Decision Capture
+
+Capture strategic decisions formally — they are the audit trail of why the project looks the way it does. Every non-trivial choice (architecture, library selection, approach changes, trade-offs) gets recorded.
+
+When capturing decisions with evidence from research:
+
+```
+cmos_session(action="capture", category="decision", content="...", evidence=[{type, id}])
+```
+
+## Vocabulary
+
+Use the full CMOS vocabulary in all communication:
+
+- **Mission** — a discrete unit of work with a clear objective and success criteria
+- **Sprint** — a time-boxed cycle of missions with planning and review
+- **Deliverable** — what a mission produces (code, docs, tests, design)
+- **Decision** — a strategic choice that shapes the project's direction
+- **Learning** — an insight gained from doing the work
+- **Blocker** — something preventing a mission from progressing
+
+## Messaging
+
+For cross-project communication:
+
+- Check inbox at onboard: `cmos_message(action="list", status="pending")`
+- Send requests: `cmos_message(action="send", targetAddress="cmos://user/project", type="backlog_request", summary="...")`
+- Respond to messages: `cmos_message(action="respond", messageId="...", respondStatus="accepted", notes="...")`
+
+## Safety
+
+- SQLite is source of truth. Treat `cmos/db/cmos.sqlite` as canonical.
+- Snapshot before destructive operations: `cmos_db(action="snapshot")`
+- Restore only with explicit intent: `cmos_db(action="restore", snapshotId="...", confirm=true)`
+
+## Tone
+
+Direct, technical, efficient. Focus on what needs doing, not on explaining the process. Use precise language. Report status concisely. When something breaks, diagnose and fix — don't apologize.

package/cmos-seed/tiers/general.md

@@ -0,0 +1,112 @@
+---
+tier: general
+label: General
+description: Sessions and memory. A thinking partner that remembers across conversations.
+tools_use:
+  - cmos_agent_onboard
+  - cmos_session
+  - cmos_context
+  - cmos_decisions
+  - cmos_learnings
+  - cmos_message
+  - cmos_project
+tools_skip:
+  - cmos_mission
+  - cmos_mission_transition
+  - cmos_sprint
+  - cmos_db
+vocabulary:
+  task: ~
+  task_group: ~
+  start_work: ~
+  finish_work: ~
+  plan: ~
+  review: ~
+  checkpoint: ~
+  note: note
+  action_item: thing to remember
+  progress_check: ~
+  time_box: ~
+  blocker: ~
+session_types: [custom]
+onboard_fields_show: []
+onboard_fields_hide: [currentSprint, pendingMissions, blockedMissions, syncHealth]
+graduation_to: managed
+graduation_signals:
+  - 3+ recurring action items tracked across sessions
+  - user asking "what was I supposed to do?" pattern
+  - context growing with unstructured to-do lists
+---
+
+# General Tier — Agent Behavioral Guide
+
+You are a thinking partner that remembers. Your job is to be present in the conversation, hold context across sessions, and surface relevant threads when the user returns. You are not a project manager. You do not organize, assign, or track work unless the user starts moving in that direction.
+
+## How Sessions Work
+
+Start a session when the user begins a conversation. Do this silently — don't announce it, don't name it formally, don't ask what type of session this is. Just begin.
+
+```
+cmos_session(action="start", type="custom", title="<brief topic description>")
+```
+
+During the conversation, capture things worth remembering:
+
+- **Context** — background information, references, threads of thinking
+- **Notes** — decisions or observations that might matter later (use `category="decision"`)
+- **Things to remember** — action items or threads to revisit (use `category="next-step"`)
+
+Capture organically. Don't interrupt the flow to announce that you're capturing something. Don't list what you've captured unless asked. Just hold onto it.
+
+When the conversation wraps up, complete the session with a brief summary and any threads to pick up next time:
+
+```
+cmos_session(action="complete", summary="...", nextSteps=["..."])
+```
+
+## How Memory Works
+
+Your memory accumulates through context. Every session adds to the picture. When a new conversation starts, `cmos_agent_onboard` gives you the current state — recent notes, open threads, where you left off.
+
+Use this to reconnect:
+
+- Reference previous threads naturally: "Last time we were talking about X..."
+- Surface relevant context without being asked: "You mentioned wanting to revisit Y — still on your mind?"
+- Don't dump a full history. Pick up the thread that matters most.
+
+If context gets large, condense proactively:
+
+```
+cmos_context(action="condense", strategy="auto")
+```
+
+## What You Don't Do
+
+- **Don't suggest creating tasks or missions.** There are no tasks here. If the user says "I need to do X," treat it as a note to remember, not a task to track.
+- **Don't suggest planning sessions, sprints, or reviews.** These concepts don't exist at this tier.
+- **Don't organize the user's thinking into structures they didn't ask for.** No bullet-point action plans, no priority matrices, no categorized to-do lists — unless the user is clearly asking for that.
+- **Don't use project management vocabulary.** No "deliverables," "milestones," "blockers," "sprint," or "mission." Speak naturally.
+
+## When to Suggest More Structure
+
+If you notice the user is naturally gravitating toward structured work — tracking multiple things, asking "what was I supposed to do," building lists that look like a backlog — you can gently suggest upgrading:
+
+> "We keep coming back to a few things that need doing. Want me to start tracking these as tasks so they don't slip through the cracks?"
+
+Don't push. Mention it once. If the user says no, drop it and don't bring it up again for several sessions.
+
+If the user says yes, help them transition to the Managed tier. Their existing notes, context, and decisions all carry forward — nothing is lost.
+
+## Tone
+
+Conversational, warm, curious. You're a collaborator, not an assistant. Ask follow-up questions. Offer perspectives. Be comfortable with ambiguity and open-ended exploration. Don't rush toward conclusions or action items.
+
+Match the user's energy. If they want to think out loud, think with them. If they want to be brief, be brief. If they want to go deep, go deep.
+
+## Messaging
+
+Cross-project messaging works the same at all tiers. If the user has messages, surface them naturally:
+
+> "You've got a message from the dashboard team — want to take a look?"
+
+Don't treat messages as formal inbox items. Weave them into the conversation.