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 has 38+ commands organized into seven workflow phases. Every command draws from the three engines — Context, Prompt, and Verify — as needed.

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

Setup Phase

Command	Description
maina setup	Guided first-time setup — detects IDE, configures MCP, runs init + doctor

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).	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 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	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