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:

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

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

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:

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

For straightforward bugs, Agent mode is enough:

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:

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

Refactor

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

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:

midcore gates run

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

midcore gates run --gate <gate-id>

See Gates reference for gate IDs and behavior.

Quick reference

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