# mycontext-cli

> The Specification & Implementation Runtime for AI-Native Development.
> Design features, maintain a **Living Brain**, and drive your codebase from natural language to working application — all from a single terminal cockpit.

[![npm version](https://img.shields.io/npm/v/mycontext-cli)](https://www.npmjs.com/package/mycontext-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

---

## What is MyContext?

MyContext is a **deterministic runtime** that reverse-engineers finished software from natural language intent. It treats `.mycontext/context.json` as a **Living Brain** — the single source of truth for your app's goals, features, components, design system, and implementation plan.

The system compiles high-level intent through a layered pipeline:

1. **Question Graph** — blocking questions that gate compilation
2. **Semantic Dictionary** — term discovery, definition, and conflict resolution
3. **Feature Graph** — dependency-ordered features with completeness scoring
4. **Implementation Graph** — batch-ordered task plans per feature
5. **Operation Pipeline** — 16 deterministic file operations with rollback
6. **Execution History** — unified audit trail
7. **Validation Daemon** — continuous structural drift detection
8. **Agent Registry** — 7 specialized AI agents with metrics persistence
9. **File Registry** — deterministic per-file tracking with drift detection
10. **Landing Page Compiler** — 14-stage manifest-driven landing page generation with validation gates
11. **Interactive TUI** — slash-command-driven terminal cockpit

---

## Installation

```bash
npm install -g mycontext-cli
# or
pnpm add -g mycontext-cli
```

Verify:

```bash
mycontext --version
```

---

## Quick Start

### Interactive Cockpit (recommended)

```bash
cd my-project
mycontext          # auto-detects setup vs chat mode
# or explicitly:
mycontext tui      # same as above
```

Booting without arguments launches the **TUI Cockpit**:
- **New project** → guided setup wizard (SetupMode)
- **Existing project** → agent chat with slash commands

### Quick Commands

```bash
# Initialize a project
mycontext init my-app

# Generate Living Brain from existing code
mycontext generate context --full

# Question-driven compilation
mycontext questions:generate "I want a daily guessing game"
mycontext questions:answer q-abc123 "Yes, one guess per day"

# Feature planning
mycontext feature:plan
mycontext impl:plan feat_daily_guess
mycontext impl:batches feat_daily_guess

# Execute the full pipeline
mycontext execute "Add a leaderboard to the game"

# File Registry — track every source file
mycontext registry:update
mycontext registry:diff                 # display drift report
mycontext registry:diff --strict        # exit 1 on untracked files
mycontext registry:diff --json          # machine-readable output

# Semantic dictionary
mycontext semantics:extract --scan src/
mycontext semantics:define SCORE_RANKING "Algorithm that sorts players by accuracy"

# Agent system
mycontext agent:list
mycontext agent:run ContextDriftAgent
mycontext agent:status
mycontext agent:metrics

# Validate everything
mycontext doctor
mycontext validate:watch                 # continuous monitoring

# Operation rollback
mycontext op:list
mycontext op:rollback op-create-file-abc123

# Security audit
mycontext doctor --red-team

# TUI Cockpit
mycontext tui

# Landing Page Compiler (14-stage pipeline)
mycontext compile-page ./my-project          # generate landing page
mycontext compile-page --fresh --verbose     # regenerate from scratch with detailed logs
mycontext compile-page --output ./custom-dir # specify output directory
mycontext compile-page --benchmark           # generate baseline comparison

# Design debt remediation
mycontext tidy .
```

---

## TUI Slash Commands

Inside the interactive cockpit, use `/` commands:

| Command | What it does |
|---------|-------------|
| `/features list` | List features with completeness scores |
| `/features graph` | Show feature dependency graph |
| `/questions list` | List blocking questions |
| `/questions blockers` | Show compilation gates |
| `/questions harvest <prompt>` | Auto-generate questions from a prompt |
| `/semantics list` | List dictionary entries |
| `/semantics search <term>` | Search dictionary |
| `/semantics define <term> <def>` | Define a new term |
| `/semantics discover <text>` | Auto-discover terms |
| `/impl plan <feature>` | Generate implementation plan |
| `/impl batches <feature>` | Show batch plan |
| `/ops plan <feature>` | Generate operations |
| `/ops execute <id>` | Execute operation batch |
| `/ops status <id>` | Check operation status |
| `/ops rollback <id>` | Roll back operations |
| `/history list` | Show execution history |
| `/history show <id>` | Show execution detail |
| `/agents list` | List registered agents |
| `/agents run <name>` | Run an agent |
| `/agents status` | Agent system status |
| `/agents metrics` | Agent metrics report |
| `/execute compile` | Compile pipeline (questions → semantics → features → impl → ops) |
| `/execute run <prompt>` | Full pipeline from prompt |
| `/doctor run` | Run all doctor rules |
| `/doctor watch` | Continuous validation |
| `/doctor rules` | List doctor rules |

---

## Environment Variables

MyContext loads `.env` files automatically (first match wins):
`.mycontext/.env.local` → `.mycontext/.env` → `.env.local` → `.env`

| Variable | Description |
|----------|-------------|
| `ANTHROPIC_API_KEY` | Anthropic Claude API key |
| `OPENAI_API_KEY` | OpenAI API key |
| `GEMINI_API_KEY` | Google Gemini API key |
| `XAI_API_KEY` | xAI (Grok) API key |

---

## Core Concepts

| Concept | Description |
|---------|-------------|
| **Living Brain** | `.mycontext/context.json` — canonical source of truth |
| **File Registry** | `.mycontext/file-registry.json` — per-file SHA256 tracking |
| **Feature Graph** | Dependency-ordered features with completeness scoring |
| **Question Graph** | Blocking questions that gate compilation |
| **Semantic Dictionary** | Term discovery, definition, conflict resolution |
| **Implementation Graph** | Batch-ordered task plans per feature |
| **Operation Pipeline** | 16 atomic file operations (create, patch, rename, delete, add-import, add-export, remove-import, add-classname, add-server-action, add-i18n-key, add-permission, add-test, add-route, add-component, add-action, add-model) |
| **Agent System** | 7 specialized agents (ContextDrift, FeatureCompleteness, SemanticDictionary, PromptToIntent, QAReplay, AdminFirst, I18n) with metrics persistence |
| **Validation Daemon** | Continuous structural drift detection with auto-fix |
| **Execution History** | Unified audit trail for all operations |

---

## Project Structure

```
.mycontext/
├── context.json             ← Living Brain (source of truth)
├── file-registry.json       ← Per-file tracking with SHA256 hashes
├── execution-history.json   ← Operation audit trail
├── agent-registry.json      ← Agent metrics persistence
├── .env.local               ← Local secrets (git-ignored)
└── specs/                   ← Auto-rendered markdown specs
    └── [feature-id]/
        ├── requirements.md
        ├── design.md
        └── tasks.md
```

---

## Links

- [Docs site](https://mycontext.ai)
- [Issues](https://github.com/farajabien/mycontext-cli/issues)
- [npm](https://www.npmjs.com/package/mycontext-cli)

---

*Built with MyContext — reverse-compiling application anatomy for the AI era.*
