判

The Engineering Blade

CodeProMax

Make AI code with engineering discipline.

CodeProMax turns software engineering practices into reusable AI skills, helping coding agents reason about architecture, implementation, quality, and maintainability.

Install CodeProMaxView on GitHub

What Is CodeProMax?

A markdown skill that turns a codebase into executable engineering work.

CodeProMax is a skill for AI coding agents — Claude Code, Cursor, Codex CLI, or similar — built around a single premise: an agent should never recommend a generic improvement without evidence from the repository it's looking at.

It is not an application and not a dependency. The whole skill is a SKILL.md file plus a references/ and templates/ directory — nothing that runs, nothing added to your package.json. "Installing" it means copying those files into your agent's own rules/skills/commands directory.

Once installed, it drives your coding agent through a disciplined reasoning chain — Problem → Evidence → Impact → Initiative → Cost → Recommendation — and classifies every important claim as FACT, INFERENCE, HYPOTHESIS, or UNKNOWN. Anything needed for planning that can't be established from evidence becomes an explicit [PLACEHOLDER] — never a guess.

The Problem

AI can generate code quickly. Speed alone doesn't produce good engineering.

Fast code generation does not automatically produce good architecture, maintainable code, consistent patterns, reliable tests, thoughtful trade-offs, or a production-quality implementation. Left unguided, an agent will often reach for a generic-sounding improvement — "improve performance," "clean this up" — with nothing behind it.

CodeProMax addresses this with reusable engineering guidance instead of one-off prompting: every recommendation has to trace back to something the agent actually found in the repository — a specific file, a specific line range, a specific behavior — before it becomes an initiative worth planning.

Don't

"Improve performance."

Do

"DashboardPage.tsx renders 47 child components on every filter change and triggers 6 API requests for a single interaction (src/pages/DashboardPage.tsx:112-140)."

What It Does

Seven capabilities, each grounded in the repository.

  1. Evidence-Based Discovery

    Reads the repository itself — architecture, code quality, testing, performance, security, observability, developer experience, dependencies, CI/CD, documentation, scalability — and classifies every claim as FACT, INFERENCE, HYPOTHESIS, or UNKNOWN.

  2. Evidence-Based Prioritization

    Ranks candidate initiatives with a scoring model built from Impact, Confidence, Urgency, and Developer Pain weighed against Effort and Risk, with the reasoning trace kept visible.

  3. Structured Planning Package

    Turns a selected initiative into a full, traceable documentation set: Initiative → Epic → Tech Spec → ADR → INVEST-validated tickets → Release Ticket → Stakeholder Report.

  4. Consistency & Drift Validation

    Checks the planning package against itself — Epic vs. Initiative, Tech Spec vs. ticket coverage, tickets vs. the INVEST gate — and reports gaps like "tech spec changed but 3 tickets are no longer aligned."

  5. Living Backlog

    Maintains initiative-register.md as initiatives are created, selected, or change status, priority, score, or scope — the central index for everything the skill has planned.

  6. Branch Review & Onboarding

    Works directly against a git branch's diff. Onboarding produces a "what changed and why" doc; Review runs an evidence-based, MUST/SHOULD/COULD-ranked review in a fixed order. Both are read-only.

  7. Ticket-to-Build-Prompt

    Converts an existing ticket, plus its Tech Spec and ADR context, into a self-contained build prompt in the AICraft schema — ready to hand to whichever coding agent will actually implement it.

How It Works

One planning cycle. Five phases. A loop, not a straight line.

  1. 01

    Discover

    Reconnaissance across architecture, code quality, testing, performance, security, observability, developer experience, dependencies, CI/CD, documentation, and scalability. Produces a ranked Top 5 opportunities — Problem / Evidence / Value / Effort / Risk — not code changes.

  2. 02

    Select

    The user picks an initiative by number or name. It becomes the source of truth for planning; the agent checks the register for duplicates before proceeding.

  3. 03

    Plan

    Generates the full documentation package in order — Initiative brief → Epic → Tech Spec → ADR → INVEST-validated implementation tickets → Release Ticket → Stakeholder Report — so none of them can drift from the same source problem.

  4. 04

    Validate

    A consistency review before the package is considered complete: does the Epic cover the Initiative, do tickets pass the INVEST gate, does the Release Ticket match what's planned. Gaps are reported directly.

  5. 05

    Maintain

    Keeps initiative-register.md in sync, resynchronizes tickets when the Tech Spec changes, and flags drift when the evidence that justified a decision no longer holds — looping back into Validate or a fresh Plan pass.

Validate can loop back into Plan when drift is found — the cycle isn't linear. Two alternate entry points skip parts of it: epic-to-dev starts straight from an epic you already wrote, and branch review / onboarding work directly against a git diff with no Initiative required. Approval stays explicit throughout — discovering an initiative never silently triggers implementation.

Installation

Install CodeProMax

The skill lives in skills/code-pro-max/ inside the CodeProMax repository. You install it into whichever project you want the skill available in — normally a different directory from the clone itself.

1. Prerequisite

Git, and one of the four supported clients already set up: Claude Code, Cursor, Codex CLI, or Antigravity.

2. Clone the skill source once

git clone https://github.com/bishoy-bishai/CodeProMax.git ~/tools/CodeProMax

Then, from your target project's root, set CPM to that path for the commands below:

CPM=~/tools/CodeProMax

3. Configuration — run the command for your client

Claude Code

Supported

Dedicated install one-liner. Project-scoped by default; a user-scoped variant is also documented in the repo.

mkdir -p .claude/skills .claude/commands && cp -r "$CPM/skills/code-pro-max" .claude/skills/code-pro-max && cp "$CPM/skills/code-pro-max/commands/code-pro-max.md" .claude/commands/

Cursor

Supported

Dedicated install one-liner, installing both the rule and the /code-pro-max command.

mkdir -p .cursor/rules/code-pro-max .cursor/commands && cp "$CPM/skills/code-pro-max/cursor-rule/code-pro-max.mdc" .cursor/rules/ && cp -r "$CPM/skills/code-pro-max/SKILL.md" "$CPM/skills/code-pro-max/references" "$CPM/skills/code-pro-max/templates" .cursor/rules/code-pro-max/ && cp "$CPM/skills/code-pro-max/cursor-rule/commands/code-pro-max.md" .cursor/commands/

Codex CLI

Supported

Dedicated install one-liner. Appends an instruction block to AGENTS.md instead of registering a slash command.

mkdir -p ~/.codex/prompts && cp "$CPM/skills/code-pro-max/codex-prompt/code-pro-max.md" ~/.codex/prompts/ && printf '\n## Engineering Improvement Initiative skill\n\nWhen asked to find engineering initiatives, audit tech debt, select/plan/validate/maintain an initiative, plan from an already-written epic, or generate an initiative/epic/tech-spec/ADR/tickets/release-ticket/stakeholder-report, follow the instructions in `%s/skills/code-pro-max/SKILL.md`, its `%s/skills/code-pro-max/references/` directory, and the templates in `%s/skills/code-pro-max/templates/`.\n' "$CPM" "$CPM" "$CPM" >> AGENTS.md

Antigravity

Manual installation

No dedicated one-liner exists yet — rule/instruction file paths vary by Antigravity release. Copy the Cursor rule content plus SKILL.md, references/, and templates/ into whatever rule file your version reads.

Copy skills/code-pro-max/cursor-rule/code-pro-max.mdc's content into whatever rule file your Antigravity version uses, alongside SKILL.md, references/, and templates/ from the same directory.

4. Verification

Open your coding agent in the target project and run /code-pro-max. It should begin describing a Discover pass over your repository rather than reporting an unrecognized command.

5. First usage

/code-pro-max

Runs Discover on the whole repository and returns a ranked Top 5 of opportunities. No files are written yet beyond each candidate's own initiative.md.

Quick Start

The smallest useful command

After installing, every client gets one slash command, /code-pro-max, which reads its argument to decide which phase to run. It also auto-triggers from plain language, with no command required.

CommandWhat it does
/code-pro-maxRuns Discover: scans the repository, presents a ranked Top 5.
/code-pro-max <path>Same as above, scoped to one path (e.g. src/api).
/code-pro-max select <n or name>Runs Select: picks an initiative as the planning target.
/code-pro-max "<name>" --buildRuns Plan end to end for that initiative.
/code-pro-max review <branch>Evidence-based code review of a branch's diff. Read-only.
/code-pro-max onboarding <branch>Generates a "what changed and why" doc for a branch. Read-only.
/code-pro-max ticket-to-prompt <id>Converts a ticket into a self-contained build prompt.

Compatibility

Supported AI Coding Agents

  • Claude CodeSupported
  • CursorSupported
  • Codex CLISupported
  • AntigravityManual installation

Compatibility here reflects what the repository documents today — it will change as the project adds dedicated installers.

Examples

Four real workflows

User request

"Analyze this repository for engineering opportunities."

CodeProMax approach

Runs Discover: reconnaissance across the whole repo, then ranks a Top 5 with Problem, Evidence, Value, Effort, and Risk for each.

Expected outcome

A ranked opportunity list and a per-candidate initiative.md. No code is changed — nothing is implemented yet.

User request

"I already have an epic — generate the tech spec and tickets from it."

CodeProMax approach

Uses the epic-to-dev entry point: skips Discover/Select, backfills a minimal Initiative from the supplied epic, runs a scoped evidence pass limited to what the epic touches, then continues into Plan.

Expected outcome

A full Tech Spec → ADR → INVEST-validated tickets → Release Ticket → Stakeholder Report package, traced back to the supplied epic.

User request

"Turn ticket ENG-142 into a build prompt."

CodeProMax approach

Runs ticket-to-prompt: pulls the ticket plus its Tech Spec and ADR context and reformats them into a self-contained prompt using the AICraft schema (Context / Goal / Constraints / Inputs / Expected Output / Definition of Done).

Expected outcome

A ready-to-hand-off build prompt for whichever coding agent will implement the ticket. CodeProMax itself still writes no code.

User request

"Review this branch."

CodeProMax approach

Resolves the branch's base, confirms it's a real ref, traces it back to a ticket or Initiative if one exists, then runs an evidence-based review in a fixed order: Scope & Intent → Architecture → Domain → Correctness → Security → Performance → Readability → Testing → Documentation.

Expected outcome

A MUST / SHOULD / COULD-ranked report with a confidence tier per finding. Read-only — it produces a report, not a fix or a verdict.

Why CodeProMax

AI shouldn't only generate code. It should reason about the engineering consequences of that code.

CodeProMax exists because evidence should come before initiative. An agent that skips straight to a recommendation has no way to tell a real problem from a plausible-sounding one — and no way for a reviewer to check its work.

That's why every important statement in the skill's output is classified as FACT, INFERENCE, HYPOTHESIS, or UNKNOWN, why unknowns become explicit [PLACEHOLDER] items instead of assumptions, and why implementation is never silent — discovering an initiative doesn't implement it; that requires an explicit decision.

FAQ

Frequently asked questions

What is CodeProMax?
CodeProMax is a markdown-only prompt skill for AI coding agents — a SKILL.md file plus a references/ and templates/ directory. There is no source code and no build step; it is not a dependency of any project.
What does CodeProMax do?
It turns "this codebase feels risky" into a ranked, evidence-backed list of specific problems, then drives a selected problem through a five-phase cycle — Discover, Select, Plan, Validate, Maintain — that produces an Initiative, Epic, Tech Spec, ADR, implementation tickets, a Release Ticket, and a Stakeholder Report. It can also review a git branch's diff, generate an onboarding doc for a branch, and convert a ticket into a build prompt.
Who should use CodeProMax?
Developers and teams already working with an AI coding agent (Claude Code, Cursor, Codex CLI, or Antigravity) who want engineering-improvement work to be evidence-backed and traceable, rather than generic or ad hoc.
How do I install CodeProMax?
Clone the CodeProMax repository once, then run the install command for your client (Claude Code, Cursor, or Codex CLI) from the root of the project you want the skill available in. See the Install CodeProMax section on this page for the exact commands.
Can I use CodeProMax with Claude Code?
Yes. Claude Code has a dedicated install command that copies the skill and registers the /code-pro-max slash command.
Can I use CodeProMax with Codex?
Yes. Codex CLI has a dedicated install command that installs the prompt and appends an instruction block to AGENTS.md.
Can I use CodeProMax with Cursor?
Yes. Cursor has a dedicated install command that installs the rule and the /code-pro-max command together.
Is CodeProMax open source?
Yes. The source is public on GitHub under the ISC License.

The Engineering Blade

CodeProMax

Built to sharpen AI-assisted software engineering.

Install CodeProMaxView on GitHub

Part of the SIMURAI Arsenal