Mana is an evidence-driven delivery framework for enterprise software delivery. It turns uneven requirements, late architecture decisions, weak tests, database risk, and overloaded reviews into governed technical workflows with traceable artifacts and explicit human approval gates.
Mana helps teams answer concrete delivery questions:
- Is this story clear, feasible, testable, and safe to start?
- Which source areas, contracts, database changes, and tests are in scope?
- Is this branch or PR consistent with the requested story?
- What evidence does a Team Leader, reviewer, Architect, or AM need before the next gate?
From the Mana repository:
scripts/validate-repo.sh
scripts/mana-doctor.sh
scripts/run-profile.sh mana-help
scripts/run-profile.sh story-start --render-onlyscripts/run-profile.sh <profile> validates Mana freshness and renders the
profile. It does not execute the listed agents or skills by itself. Add a runner
flag only when you want local runner-backed execution:
scripts/run-profile.sh story-start --codex
scripts/run-profile.sh story-start --claudeCodex runs start on the cost-saving model configured by
MANA_CODEX_MODEL or --codex-model (default: gpt-5-mini). Mana also passes
an escalation target from MANA_CODEX_FULL_MODEL or --codex-full-model
(default: gpt-5). If a run needs a high-risk or explicitly full-model skill,
the agent must stop with needs_model_escalation and ask you to rerun the same
profile with the full model instead of spending deep-analysis tokens blindly.
To use Mana inside a target application repository:
/path/to/mana/scripts/bootstrap-project.sh --project-root /path/to/project
cd /path/to/project
./mana workspace status
./mana profile mana-help
./mana profile story-start --render-only
./mana profile story-start --codex
./mana dependency-evidence --collect
./mana evidence-indexThe bootstrap creates a project-local ./mana wrapper, .mana/ evidence
workspace, links to framework definitions, and AGENTS.md / CLAUDE.md runner
instructions. Project artifacts stay under the target repository's .mana/
workspace.
- An evidence-driven delivery framework.
- A structured way to orchestrate AI-assisted technical workflows.
- A repository of profiles, agents, skills, standards, bootstrap scripts, MCP wrappers, templates, and workspace rules.
- A way to support human decisions with traceable requirement, code, test, architecture, release, and review evidence.
- A fully autonomous developer.
- A replacement for human review or owner accountability.
- A CI/CD platform.
- A Jira, GitHub, or service-management replacement.
- A system that should approve, merge, deploy, release, transition tickets, or publish externally without explicit human control.
- Profiles are runnable workflow definitions. They name the trigger, runner, agents, skills, blocking conditions, warnings, duration, and approval rules.
- Agents orchestrate a phase such as story planning, branch validation, PR readiness, requested PR review, architecture review, or AM readiness.
- Skills are atomic reusable checks that produce reports, plans, questions, and recommendations.
- MCP wrappers provide governed integrations such as read-only Jira access.
- Workspace rules route generated artifacts into the project-local
.mana/evidence workspace. - Runners such as Codex or Claude interpret the rendered profile. Junie is used inside the IDE for local implementation support.
Codex is used for repository-level planning, validation, documentation, branch analysis, PR readiness, and learning. Junie is used inside the IDE for local code implementation, test generation, local fixes, green-border execution, and fast developer feedback. Claude Code is used as a CLI runner for repository-level analysis and local development support. Do not let two runners modify the same branch at the same time.
| Role | When | Mana workflow/profile | Output | Decision supported |
|---|---|---|---|---|
| Team Leader / Tech Lead | Before assigning or sequencing work | story-ready-for-dev, team-planning, team-coaching-review |
Readiness report, story effort estimate, execution sequence, delivery risks, review-load plan, coaching report | Start/no-start, task split, sizing, ownership, reviewer focus, coaching priorities |
| Developer | Before and during implementation | story-start, dev-assist, pre-commit, .junie/profiles/technical-task-execution.md |
Story context, source impact map, implementation plan, test plan, development summary, handoff notes | What to build, what not to touch, which tests prove the change |
| Reviewer | When review is requested or PR package is needed | requested-pr-review, pr-ready, branch-ready |
PR risk report, reviewer focus, defect findings, test evidence, PR package | Which PR to review first, which findings block, what evidence is missing |
| Architect | When design, boundary, NFR, trust, contract, or database risk is material | architecture-review |
Architecture review report, ADR material, NFR and drift findings, approval questions | Approve, reject, or require mitigation for architectural trade-offs |
| AM / Release Owner | Before release or go/no-go discussion | am-release-ready |
Release impact, continuity, incident-risk, rollback, support, communication evidence | Release readiness, operational mitigations, stakeholder communication |
| Delivery Manager / PM | During planning, dependency review, and delivery governance | team-planning, story-ready-for-dev, mana-help |
Dependency map, delivery risk radar, open questions, readiness status | Scope clarity, escalation timing, delivery risk acceptance |
This path shows how existing profiles fit together for a realistic enterprise change. Mana produces evidence for humans; it must not automatically code, approve, merge, release, transition Jira, or publish externally unless a profile explicitly allows a narrow action and the human enables it.
| Step | Purpose | Profile or command | Expected output | Human decision supported | Mana must not do automatically |
|---|---|---|---|---|---|
| Jira story | Read the requested behavior and acceptance criteria | ./mana jira-mcp --get-issue PROJ-1234 when Jira is configured |
Story JSON or reported access gap | Whether the available requirement evidence is enough | Update Jira, infer missing AC, expose credentials |
| Story evidence / readiness | Check feasibility, scope, testability, dependencies, approvals, and estimate | ./mana profile story-start --codex or ./mana profile story-ready-for-dev --codex |
Story context, readiness findings, effort estimate, open questions, risk register | Start, clarify, split, size, or block the story | Invent requirements or mark owner approval as complete |
| Epic story pack | Cache epic and sibling story evidence as Markdown | ./mana jira-mcp --fetch-epic-story-pack PROJ-1234 |
.mana/features/<EPIC-ID>/evidence/jira/epic-story-pack.md |
Whether stories are partitioned, overlapping, missing slices, or ready for planning | Edit Jira, store credentials, or treat cached evidence as permanent truth |
| Local evidence index | Build a compact map of available evidence before deep analysis | ./mana evidence-index after Jira, Sonar, dependency, test, validation, or PR evidence exists |
.mana/<workspace>/evidence/index.md |
Which evidence to inspect first and which gaps remain | Treat missing evidence as proof of safety |
| Source impact analysis | Identify likely code, tests, contracts, database areas, and protected zones | story-start output, team-planning, or dev-assist |
Source impact map and inspection scope | What can be changed and what requires approval | Modify files outside the approved scope without asking |
| Developer assistance | Support bounded implementation work | ./mana profile dev-assist --codex or Junie profile .junie/profiles/technical-task-execution.md |
Change impact preview, pitfalls, test gaps, local task guidance | Whether the planned local change is still within scope | Run broad autonomous refactors |
| Branch validation | Compare branch evidence against story, plan, tests, and risks | ./mana profile branch-ready --codex |
Branch validation report, plan-drift findings, missing-test evidence | Whether the branch is ready for PR | Pick an ambiguous base branch silently |
| Dependency evidence | Record local dependency manifests, lockfiles, and existing scanner reports when dependency surfaces changed | ./mana dependency-evidence --collect |
.mana/<workspace>/evidence/dependencies/dependency-summary.md |
Whether dependency/security follow-up is needed before review | Invent CVEs or replace project-approved security scanners |
| Requested PR review | Triage requested reviews or analyze one PR | ./mana profile requested-pr-review --pr <number> --codex |
PR risk summary, review focus, high-signal findings | What the reviewer should inspect or block | Approve, request changes, merge, label, or comment unless explicitly enabled |
| Architecture review if needed | Review ADR, NFR, service boundary, trust, contract, or database concerns | ./mana profile architecture-review --codex |
Architecture report, drift and approval questions | Whether specialist owner approval is required | Treat architecture approval as implicit |
| AM / release readiness | Translate technical change into release, rollback, continuity, and support evidence | ./mana profile am-release-ready --codex |
Release impact, incident-risk forecast, continuity and rollback findings | Go/no-go readiness and operational mitigations | Release, deploy, trigger CI, or accept operational risk |
| Developer handoff / PR package | Prepare review and handoff artifacts | ./mana profile pr-ready --codex and optionally ./mana profile pre-commit --codex |
PR description, reviewer focus, test evidence, development summary, handoff notes | Whether the PR package is understandable and reviewable | Hide unresolved blockers or replace reviewer judgement |
Mana currently provides the framework structure, governance model, reusable skill/agent definitions, profile metadata, artifact templates, workspace management, Jira MCP wrapper, project bootstrap, and diagnostics.
Enterprise delivery churn usually starts before coding: stories are vague, cross-service contracts are implicit, database changes are reviewed late, and tests are selected by habit rather than risk. The framework reduces analysis, development, review, testing, database deployment, cross-service integration, and regression churn by making evidence explicit at each lifecycle gate.
docs/ Architecture, workflow, deployment, problems, and examples.
skills/ Atomic reusable capabilities with SKILL.md files.
agents/ Orchestrators with AGENT.md, playbooks, schemas, and examples.
profiles/ Triggerable workflow profiles.
mcp/ Broker policy and tool-server definitions.
templates/ Markdown artifact templates.
scripts/ Validation and helper scripts.
hooks/ Local Git hook entrypoints.
.codex/ Codex usage guidance and profiles.
.junie/ Junie usage guidance and profiles.
From a target application repository, run:
/path/to/mana/scripts/bootstrap-project.shThis creates a small local ./mana wrapper, .mana/ links to the framework,
the project-local .mana/ artifact workspace, and AGENTS.md and CLAUDE.md
in the project root so Codex and Claude Code load Mana instructions automatically
at session start. See docs/deployment/project-link-bootstrap.md.
For a complete Jira-free flow from epic input to PR readiness, see
docs/examples/end-to-end-codex-flow.md.
Projects using this framework keep a .mana/ directory at repository root.
This is where runners, agents, and skills store planning files, agent memory,
skill outputs, decisions, test evidence, validation reports, PR material, and
learning artifacts.
.mana/global/is the Service Context Layer: service mission, architecture, engineering guards, glossary, integration map, and testing/database policy.engineering-guards.mdholds the "must not do" rules; violations block or require explicit owner approval.- Feature work goes under
.mana/features/<FEATURE-ID>/, with a canonicalagent-memory/story-trace.mdper story (docs/standards/story-trace-standard.md) and adecisions/developer-choice-log.mdfor developer-confirmed choices (docs/standards/developer-choice-log-standard.md). - Canonical branches (
main,develop,release/*, …) use session workspaces under.mana/sessions/.
Workspace resolution and routing rules are defined in
docs/workflow/mana-workspace.md; the Service Context Layer is described in
docs/workflow/service-context-layer.md. Use ./mana evidence-index after
collecting Jira, Sonar, dependency, test, validation, or PR artifacts so
agents read a compact index before deep-loading evidence.
flowchart TD
Story[Story or Epic] --> Req[Requirement Intelligence]
Req --> Plan[Planning and Technical Slicing]
Plan --> Dev[Development and Green Border]
Dev --> Validate[Branch Validation]
Validate --> PR[PR Readiness]
PR --> Merge[Merge and Deploy]
Merge --> Learn[Knowledge and Learning]
Learn --> Req
Skills are plain directories under skills/. Each SKILL.md declares inputs,
outputs, allowed tools, preferred runner, owner role, risk level, stack
applicability, and examples. The stack front matter field names the
technology or tooling the target project must use for the skill to apply
(for example java, liquibase, sonar) or any; runners and the profile
selector use it to discard non-applicable skills without deep-loading them.
Import only the skills needed by a profile or agent. Skills should analyze,
report, and suggest; they should not perform broad autonomous changes.
Agents are directories under agents/. Read AGENT.md, follow playbook.md,
validate inputs against inputs.schema.json, and store outputs listed in
outputs.schema.json. Agents compose skills and stop at human approval gates.
Agent outputs should be routed into the active .mana/<workspace>/ directory.
All skills and agents follow docs/standards/agent-skill-output-standard.md.
It defines the required artifact sections, the fixed instruction priority
(human instruction → profile YAML → AGENT.md → playbook.md → SKILL.md →
global service context, with safety and approval rules only getting stricter
down the chain), the operating loop for profile runs, progressive skill
loading, compact "caveman" working notes, and the context budget for
long-running profiles. Use
templates/standard-agent-skill-report.template.md when a more specific
artifact template does not exist.
Task-oriented recipes — which profile, skill, or command to use for a given
situation (story intake, Jira evidence, Sonar, dev assist, branch validation,
PR review, release readiness, coaching, freshness check) — live in
docs/workflow/cookbook.md. A few common entry points:
- Not sure what to run:
scripts/run-profile.sh mana-help, orscripts/run-profile.sh tutorialfor an interactive walkthrough. - Start a story:
./mana profile story-start --codex(or--claude). - Validate a branch before PR:
./mana profile branch-ready --codex. - Review a PR you were asked to review:
scripts/run-profile.sh requested-pr-review --pr <number> --codex.
AI supports, analyzes, documents, suggests, and validates. It does not replace accountability. BA/PO owns requirement clarity; Team Leader and Architect own technical decisions and approval; Developers own implementation and final correctness; DBA/Security owners approve high-risk database or trust-boundary findings.
Use MCP least privilege, environment separation, audit logs, data redaction, and
explicit approval for destructive or external writes. Jira MCP access is
read-only by default: agents may read issue context when issue keys are provided
or discovered from the branch, but must not expose tokens, transition issues,
add comments, or update tickets without explicit human approval. Optional GitHub
CLI access is read-only by default: agents may read PR metadata, changed files,
diffs, checks, and reviewer requests, but must not approve, comment, merge,
edit, label, or assign without explicit human approval. A requested PR review
run may publish one gh pr comment only with a selected PR and an explicit
publish flag, and only for blocker or high-criticality findings. Never expose
secrets or production data in prompts, reports, or logs. Destructive database,
repository, Jira, GitHub, or CI operations must be human-approved.
Read CONTRIBUTING.md. New skills must be atomic, include required front
matter, examples, decision rules, failure modes, MCP behavior, and human review
gates. New agents must orchestrate existing skills rather than duplicate logic.