Skip to main content

Common workflows

Patterns for everyday tasks: exploring the codebase, fixing bugs, refactoring, adding features, running gates, and working with Git.

Explore the codebase

Use Ask mode (read-only) or the agent with a question:

bash
midcore ask "what does this project do? where is the main entry point?"

For a more interactive exploration that can follow up with suggestions:

bash
midcore agent "summarize the architecture and list the main modules"

Fix a bug

Describe the symptom or paste the error. Use Debug mode when you want multiple hypotheses and targeted fixes:

bash
midcore debug "users get 500 on /api/profile"

For straightforward bugs, Agent mode is enough:

bash
midcore agent "fix the login bug: blank screen after wrong password"

Add a feature

Describe the feature in plain language. The agent will align with contracts when the project uses the Outcome Compiler, then implement:

bash
midcore agent "add rate limiting to all public API endpoints"

Contracts first

If your repo uses intent and gates, define or update contracts before implementation so the agent and gates stay in sync. See Outcome Compiler.

Refactor

Use Plan mode first to agree on scope and approach, then Agent mode for the changes:

bash
midcore plan "refactor auth: move JWT logic into a shared service"

After you approve the plan, run the same intent in Agent mode or let the agent execute the plan. Run tests and gates afterward to catch regressions.

Working with Git

Commit, branch, and open PRs as usual. The agent does not run Git for you by default; you control when to commit and push. Use midcore gates run before merging. See CLI reference for Git-related flags if your environment supports them.

Running in CI

Run midcore gates run in your CI pipeline (e.g. GitHub Actions, GitLab CI) to ensure every merge passes the same gates and evidence is recorded. Set required environment variables (API URL, auth) in your CI secrets. For a full CI/CD guide, see CI/CD and FAQ.

Run gates and record evidence

Before a release or in CI, run all applicable gates:

bash
midcore gates run

Evidence is written to the evidence ledger. Use it for audit and compliance. To run a single gate:

bash
midcore gates run --gate <gate-id>

See Gates reference for gate IDs and behavior.

Quick reference

TaskCommand
Explore (read-only)midcore ask "…"
Implement or fixmidcore agent "…"
Design / planmidcore plan "…"
Debug with hypothesesmidcore debug "…"
Run all gatesmidcore gates run
Initialize projectmidcore init

Key takeaways

  • Use Ask or agent with a question to explore; use Agent for implementation, Plan for design, Debug for failure tracing.
  • Run gates before releases and in CI; evidence is recorded in the ledger.
  • Working with Git and running in CI are standard: you commit and push; CI runs midcore gates run.

Related documentation

Best practices · How Midcore works · CI/CD · CLI reference