Commands

flowchart TD
  subgraph Discovery["Discovery"]
      brainstorm["maina brainstorm"]
      ticket["maina ticket"]
  end
  subgraph Planning["Planning"]
      plan["maina plan"]
      design["maina design"]
      spec["maina spec"]
  end
  subgraph Execution["Execution"]
      implement["implement (TDD)"]
      verify["maina verify"]
      review["maina review"]
      fix["fix findings"]
  end
  subgraph Ship["Ship"]
      commit["maina commit"]
      review2["maina review"]
      pr["maina pr"]
  end
  subgraph Wiki["Wiki"]
      wikiInit["maina wiki init"]
      wikiQuery["maina wiki query"]
      wikiLint["maina wiki lint"]
  end

  brainstorm --> ticket --> plan --> design --> spec
  spec --> implement --> verify --> review --> fix
  fix --> commit --> review2 --> pr
  pr --> wikiInit --> wikiQuery --> wikiLint

  style Discovery fill:#1e3a5f,stroke:#3b82f6,color:#93c5fd
  style Planning fill:#3b1f5e,stroke:#8b5cf6,color:#c4b5fd
  style Execution fill:#1a3a2a,stroke:#22c55e,color:#86efac
  style Ship fill:#164e63,stroke:#22d3ee,color:#a5f3fc
  style Wiki fill:#4a1942,stroke:#e879f9,color:#f0abfc

Maina commands are organized into seven workflow phases. Every command draws from the three engines — Context, Prompt, and Verify — as needed. Run maina --help to see the live top-level surface (internal commands like analyze, stats, and sync are hidden from top-level help but still callable by name).

Commands that support --json for machine-readable output (JSON envelope with { data, error, meta }): analyze, commit, context, doctor, review, slop, stats, verify, wiki status.

Setup Phase

Command	Description
maina setup	Guided first-time setup — detects stack, derives constitution from your existing rule files, materialises skills, kicks off the wiki in background. --yes skips prompts; --ci emits one JSON object per phase; --update re-tailors; --reset backs up .maina/ and starts fresh.
maina doctor	Health check across tools, engines, AI status, wiki coverage, and MCP integrations. Reads both project-local and user-global MCP configs (~/.claude/settings.json, ~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json, ~/.config/zed/settings.json) and reports scope per client: project, global, both, or missing.
maina doctor --fix	Iterate every missing MCP row and execute its printed maina mcp add --client X --scope global remediation. Confirms interactively; --yes skips (--json implies --yes).
maina doctor --json	Emit {tools, engines, aiStatus, wikiHealth, mcpHealth: { integrations: [{client, scope, fix?}] }, cacheStats} for CI consumption.
maina mcp add	Install the maina MCP server in every detected client’s global config (Claude Code, Cline, Codex, Continue, Copilot, Cursor, Gemini CLI, OpenHands, Roo Code, Windsurf, Zed AI). Auto-detects; pass --client <list> to override or --scope project for per-repo install.
maina mcp remove	Strip the maina MCP entry from each client’s config. Defaults to global scope; same --client / --scope global|project|both / --dry-run / --json flags as add.
maina mcp list	Show maina MCP install status per client.

Brainstorm Phase

Start here. Explore ideas before committing to implementation.

Command	Description	Context Needs
maina brainstorm	Interactive idea exploration — generates a structured GitHub issue with user stories, acceptance criteria, edge cases. The starting point for every feature.	None

Define Phase

Set up your project and define architecture.

Command	Description	Context Needs
maina init	Bootstrap Maina in any repo. Creates .maina/ directory, constitution, AGENTS.md, default prompts.	None
maina init --install	Auto-install missing verification tools after bootstrapping.	None
maina configure	Interactive project settings — update constitution, conventions, visual URLs, tool preferences.	None
maina ticket	Create a GitHub Issue with automatic module tagging. Use --repo for cross-repo issue creation with aliases from .maina/config.json.	Semantic (module structure)
maina context	Generate focused codebase context. Loads all 4 layers in exploration mode (80% budget). Writes to .maina/CONTEXT.md by default; use --output <path> to override. An existing CONTEXT.md at repo root is preserved unless --force.	All 4 layers (exploration)
maina explain	Visualize codebase structure with Mermaid dependency diagrams and module summaries.	Semantic (dependency graph)
maina design	Create an Architecture Decision Record (ADR) with HLD/LLD sections. Use --hld for AI generation. Use --auto for fully automated ADR creation from plan context.	Semantic (existing ADRs)
maina review-design	Review an ADR against existing decisions and the project constitution. Blocks empty ADRs.	Semantic (ADRs + constitution)

Build Phase

Plan, specify, and commit.

Command	Description	Context Needs
maina plan	Create a feature branch with auto-numbered directory and structured spec/plan/tasks. Resets workflow context.	Working + Semantic
maina spec	Generate TDD test stubs from plan. Scores spec quality across clarity, testability, completeness. Use --auto for fully automated spec generation without prompts.	Working + Episodic
maina commit	Run syntax guard, parallel verification (19+ tools), then git commit. Records stats + workflow step.	Working only (fast)

Verify Phase

Prove correctness before merge.

Command	Description	Context Needs
maina verify	Full verification pipeline (19+ tools). Diff-only by default.	Working + Semantic
maina verify --deep	Add standard-tier AI semantic review (spec compliance, architecture).	Working + Semantic
maina verify --cloud	Submit diff to Maina Cloud for hosted verification. No local tool installs required.	Working
maina verify --visual	Add Playwright visual regression checks against baselines.	Working + Visual baselines
maina slop	Standalone AI slop pattern detection. --all for all tracked files.	Working
maina review	Comprehensive two-stage code review: spec compliance first, then code quality.	Working + Semantic
maina analyze	Check cross-artifact consistency: spec, plan, tasks, and code must align.	Semantic (all artifacts)
maina pr	Create a pull request with two-stage review + verification proof artifacts in the body.	All 4 layers

Cloud Integration

Authenticate, sync prompts, and manage teams.

Command	Description
maina login	GitHub OAuth device flow. Stores token in ~/.maina/auth.json.
maina logout	Clear stored credentials from ~/.maina/auth.json.
maina sync push	Upload local prompts and constitution to the Maina cloud.
maina sync pull	Download team prompts and merge with local copies (conflict resolution included).
maina team	Show team info, members, and roles.
maina team invite <email>	Send an invite to join the team.

Wiki Phase

Compile and query codebase knowledge.

Command	Description	Context Needs
maina wiki init	Compile codebase knowledge wiki from code, plans, specs, ADRs, workflows	Working, Semantic
maina wiki init --background	Fork the compile, seed .maina/wiki/.progress.json, return immediately. Poll with maina wiki status. maina setup uses this to keep onboarding under 60 s.	Working, Semantic
maina wiki init --depth quick	Compile only the top 20 PageRank-scored files. Used by setup’s background seed.	Working, Semantic
maina wiki compile	Incremental recompilation. --full for complete. --ai for LLM enhancement. --dry-run to preview.	Working
maina wiki query <question>	AI-powered search across wiki articles. --save to persist answer.	Wiki (L5)
maina wiki status	Health dashboard: articles by type, coverage, staleness, last compile. When a background compile is running, shows Compiling… N% + ETA; marked stalled when the progress file hasn’t been updated in 10+ minutes. --json emits the structured snapshot.	None
maina wiki lint	Check wiki for stale articles, broken links, spec drift, decision violations	Working, Semantic
maina wiki ingest <source>	Add external docs to wiki/raw/ for compilation	None

Meta

Tune, learn, and diagnose.

Command	Description
maina learn	Analyze feedback patterns across tasks and workflow steps. Propose prompt improvements via A/B testing. Use --no-interactive for CI.
maina visual update	Capture current screenshots as visual baselines for regression testing.
maina prompt edit <task>	Open a custom prompt template in $EDITOR.
maina cache stats	Show cache hit rate, total entries, tokens saved.
maina stats	Show commit verification metrics, trends, and quality evolution.
maina benchmark	Run verification benchmarks comparing tools.
maina doctor	Check tool installation status (19+ tools) and engine health.
maina status	Show current workflow state, active feature branch, and verification summary.

Verification Pipeline

Maina’s verify pipeline runs 19+ tools in parallel:

Tool	Type	Language
Biome	Syntax guard	TypeScript/JavaScript
ruff	Linter	Python
go vet	Linter	Go
clippy	Linter	Rust
PHPStan/Psalm	Static analysis	PHP
TypeScript (tsc)	Type checking	TypeScript
Semgrep	SAST (2000+ rules)	All
Trivy	Dependency CVEs	All
Secretlint	Secret detection	All
SonarQube	Quality gates	All
Stryker	Mutation testing	TypeScript/JavaScript
diff-cover	Coverage on changed lines	All
Consistency check	Cross-artifact alignment	All
ZAP	DAST / web security scanning	All
Lighthouse	Performance and accessibility audits	Web
AI review	Semantic code review	All
Slop detector	AI-generated pattern detection	All
Playwright	Visual regression testing	Web

Tools are auto-detected and auto-skipped if not installed. Run maina doctor to see status.

Multi-Language Support

Maina detects your project language from marker files and adapts:

Language	Marker Files	Syntax Tool
TypeScript	tsconfig.json, package.json	Biome
Python	pyproject.toml, setup.py, requirements.txt	ruff
Go	go.mod	go vet
Rust	Cargo.toml	clippy
PHP	composer.json	PHPStan / Psalm
C# (.NET)	.sln, .csproj, global.json	dotnet format
Java/Kotlin	pom.xml, build.gradle	Checkstyle

Workflow Context

Every command records its outcome to .maina/workflow/current.md. This rolling summary is forwarded between steps so each phase has context from prior phases. Background RL feedback records every step for prompt evolution.

Exit Codes

All commands return structured exit codes for CI integration:

Code	Meaning	Description
0	Passed	No error-severity findings
1	Findings	Error-severity findings found
2	Tool failure	A verification tool crashed
3	Config error	Missing config, bad arguments

Common Workflows

First-time setup

maina init --install    # Bootstrap + install verification tools
maina configure         # Set architecture constraints and conventions
maina doctor            # Verify tool health

Daily development

maina plan my-feature   # Start feature with structured planning
maina spec              # Generate TDD test stubs
# ... write code ...
maina commit            # Verify (19+ tools) and commit
maina pr                # Create PR with verification proof

Visual verification

maina configure         # Set visual URLs
maina visual update     # Capture baseline screenshots
# ... make changes ...
maina verify --visual   # Compare against baselines

Prompt tuning

maina learn             # Analyze per-step feedback and evolve prompts
maina stats             # Track improvement over time