Apex Workflow

A repo-native control plane for Codex and LLM coding agents. Stop letting agents improvise your engineering process. Install a harness that forces orientation, scope control, contract routing, MCP/GitNexus impact checks, verification, and clean handoff state.

The Short Version

Apex Workflow turns a repository into an agent-operable system: it installs an app-specific workflow profile, gives the agent a mode/state machine, and records every meaningful slice in a manifest before code gets touched. The result is less vague "I changed some files" automation and more controlled engineering: known authority docs, scoped ownership, explicit no-touch surfaces, code-intelligence checks, focused verification, and a next safe slice.

Why This Exists

Most LLM coding agents do not fail because they cannot write code. They fail because they enter a repo with no operational discipline.

They search before reading the authority chain. They edit shared surfaces as if they were local helpers. They lose track of which files belong to the current slice. They treat screenshots as visual signoff. They skip tracker state or create junk tickets. Then the next session has to reconstruct the mess from a dirty tree and half-remembered chat.

Apex is the antidote: a portable workflow harness that makes the agent follow the repo's actual operating model.

Trust Model

Apex profiles and manifests are trusted executable workflow configuration. Some Apex commands run shell commands declared in the profile, manifest, or CLI arguments. Read SECURITY.md before installing Apex into an unfamiliar repository or running manifests from another source.

Release Posture

Apex is currently a private package and does not publish to npm. Tagged v* release workflow runs are artifact-only: they run npm run hardening-check, generate an SBOM, create a local package tarball, and upload the artifacts to the workflow run. Signed tags, GitHub artifact attestations, and npm provenance are future upgrades documented in SECURITY.md.

Remote Policy

Apex requires a normal Git repo and uses origin as the working remote when GitHub-backed workflows are needed.

A local upstream remote is optional. Apex must not fail install, doctor, manifest creation, verification, close, or finish-packet generation because upstream is missing.

upstream is only relevant for explicit parent-sync, fork-drift comparison, or contributing changes back to a parent repository.

Architecture

APEX WORKFLOW CONTROL PLANE

[apex-workflow repo]
  scripts/init-harness.mjs
  scripts/check-config.mjs
  scripts/apex-map-codebase.mjs
  scripts/apex-doctor.mjs
  scripts/apex-manifest.mjs
  skills/apex-workflow/SKILL.md
        |
        | install / refresh
        v
[target application repo]
  AGENTS.md managed block
  apex.workflow.json
  .gitignore managed Apex local-artifact block
  tmp/apex-workflow/ ignored local manifests, logs, and observations
  repo docs / contracts / tests
        |
        | every agent run reads the profile
        v
[$apex-workflow agent skill]
  mode selector
  manifest discipline
  contract + routing gates
  finish packet handoff
        |
        | adapter layer from apex.workflow.json
        v
[external intelligence + ops]
  GitNexus MCP first
  GitNexus wrapper fallback
  Linear / GitHub / file tracker
  agent-browser
  focused source search

Execution State Machine

[user task]
    |
    v
[1. orient]
    read AGENTS.md, apex.workflow.json, authority docs
    |
    v
[2. select mode]
    tiny | route-local | shared-surface | issue-resume | planning | reconciliation
    |
    |-- tiny known fix -------------------------------+
    |                                                |
    v                                                |
[3. open slice manifest]                             |
    owned files, no-touch surfaces, checks           |
    |                                                |
    v                                                |
[4. route before edit]                               |
    owner docs, contracts, state, callers            |
    |                                                |
    v                                                |
[5. impact check]                                    |
    GitNexus MCP -> wrapper fallback -> search       |
    |                                                |
    v                                                |
[6. edit]                                            |
    narrow implementation inside declared scope      |
    |                                                |
    v                                                v
[7. verify] <-------------------------------- [direct fix]
    path-scoped tests, lint/typecheck/build/browser evidence when relevant
    record command results into the manifest
    |
    v
[8. detect scope]
    compare changed files and affected flows against the manifest
    built-in dirty-file coverage if no graph detect is configured
    |
    v
[9. finish packet]
    landed, verified, not verified, risks, next safe slice

Install

From the Apex repo, make the local CLI shims available during development:

npm link

First-time adopters can follow the no-service path in docs/quickstart.md.

Agents installing Apex should inspect the target repo first, then pass explicit adapter choices. Repo evidence can help choose those options, but the installer no longer treats heuristic auto config as authority.

apex-init \
  --target=/path/to/app \
  --config-mode=custom \
  --tracker=linear \
  --tracker-team="Team Name" \
  --tracker-project="Project Name" \
  --code-intelligence=gitnexus-mcp \
  --browser=agent-browser \
  --origin=http://127.0.0.1:3000 \
  --yes

The installer writes local apex.workflow.json, adds a managed Apex block to the target repo's AGENTS.md, updates a managed .gitignore block for Apex local files, validates the profile, and symlinks the $apex-workflow skill into the local Codex skills directory.

It also prints an install report: inferred authority paths with confidence, adapter choices, dirty repo state, review items, and whether to commit the harness setup before the first implementation slice.

Before the first implementation slice, manually review and harden the generated profile against the target repo's real authority chain, tracker/backlog needs, verification scripts, browser smoke requirements, security boundaries, and slice templates. Discovery remains advisory; use apex-profile discover or apex-init --discover to collect candidate profile recommendations, not to replace repo-specific judgment.

Before the first implementation slice, run the doctor against the target repo:

apex-doctor --target=/path/to/app --config=apex.workflow.json

The doctor checks unresolved setup review items, guessed inferred paths, whether apex.workflow.json and tmp/apex-workflow/ are ignored, the managed AGENTS.md block, adapter readiness, the local skill symlink, and whether the repo-facing setup has a clean baseline checkpoint.

Create A Codebase Map

If the install report says no broad-search orientation doc was detected, create a draft map:

apex-map-codebase --target=/path/to/app --write

The generated docs/CODEBASE_MAP.md starts as Status: draft. It is a scaffold, not authority. Review the file, resolve every REVIEW NEEDED marker, then mark it reviewed and sync the profile:

cd /path/to/app
apex-map-codebase --target=. --mark-reviewed --sync-profile
apex-map-codebase --target=. --check --require-reviewed

apex-init --create-codebase-map can create the draft during install. It keeps a setup review item until the map is reviewed so agents do not treat generated guesses as confirmed routing truth.

What The Profile Controls

apex.workflow.json is the contract between the target app and the agent.

{
  "authority": {
    "productTruth": ["PRD.md"],
    "executionTruth": ["ROADMAP.md"],
    "workflowRules": ["AGENTS.md"]
  },
  "tracker": {
    "provider": "linear"
  },
  "codeIntelligence": {
    "provider": "gitnexus-mcp",
    "wrapperFallback": {
      "enabled": true
    }
  },
  "manifest": {
    "defaultDir": "tmp/apex-workflow"
  }
}

It tells the agent what counts as product truth, what workflow rules to read, which tracker to use, whether GitNexus runs through MCP or a wrapper, where contract docs live, which checks matter, and how browser evidence should be treated.

Modes

Mode	Use When	Guardrail
tiny	One known file, low blast radius	Direct file read, path-scoped check
route-local	One owner with obvious callers	Manifest, owner docs, focused verification
shared-surface	Shared shell/store/hook/auth/workspace	Contracts, impact analysis, no-touch list
issue-resume	Named tracker issue or dirty continuation	Latest state, first real gap, no widening
planning	Product/design/architecture before code	Durable decision artifact when useful
reconciliation	Code landed, remaining work is review/tracker/audit	Evidence packet, no reopened code flow

GitNexus Strategy

Apex is MCP-first.

When GitNexus is selected, the profile prefers:

• gitnexus_query
• gitnexus_context
• gitnexus_impact
• gitnexus_detect_changes
• gitnexus://repo/{name}/context

If MCP fails because of host config, runtime, stale reloads, or local storage issues, Apex records a wrapper fallback. That wrapper should expose the same intent through repo-local commands like npm run gitnexus:status, npm run gitnexus -- impact <symbol>, and manifest-backed detect_changes.

MCP is the clean path. The wrapper is the survival path.

The profile records these separately:

• configured preference
• detected repo support
• current host availability
• fallback command readiness

Install-time repo evidence can detect wrapper scripts or GitNexus markers, but host MCP availability is only proven in the active agent session.

Manifests And Finish Packets

Use the configured manifest directory instead of hand-writing tmp/apex-workflow paths:

apex-manifest new \
  --config=apex.workflow.json \
  --slug=app-123-thing \
  --issue=APP-123 \
  --mode=route-local \
  --surface="ticket detail route" \
  --downshift="route-local: one owner and focused checks cover this slice"

Run detect immediately after manifest creation. This catches wrong schema, placeholder fields, missing required check disposition, and dirty files outside the manifest before implementation starts. Reconciliation manifests default to dirtyPolicy=owned-files-only, so unrelated dirty files are recorded as external state instead of failing the slice:

apex-manifest detect \
  --config=apex.workflow.json \
  --slug=app-123-thing

Record checks as executable evidence:

apex-manifest run-check \
  --config=apex.workflow.json \
  --slug=app-123-thing \
  --cmd="npm test"

Command runs are recorded in checks.runs with command source, exit code, timestamps, cwd, git head, evidence fingerprints, stdout/stderr tails, timeout metadata, and a hashed log file under tmp/apex-workflow/logs/<slice>/. Command output and persisted command strings are redacted for common token shapes. The default command timeout is 120000 ms; override it per run with --timeout-ms=<milliseconds> when a legitimate check needs longer.

Record manual terminal, TUI, or operator evidence without pretending it was an automated check:

apex-manifest record-evidence \
  --config=apex.workflow.json \
  --slug=app-123-thing \
  --kind=manual-terminal \
  --summary="Inspector resumed the real session id and side panel loaded" \
  --source="local TUI"

For GitNexus-enabled non-tiny code slices, record freshness evidence before close:

apex-manifest record-gitnexus-freshness \
  --config=apex.workflow.json \
  --slug=app-123-thing \
  --phase=pre-status \
  --status=fresh \
  --command="npm run gitnexus:status"

If the pre-slice status is stale or missing, refresh and record --phase=pre-refresh --status=refreshed. After graph-relevant code changes, refresh and record --phase=post-refresh; otherwise record --phase=post-skip --status=skipped --reason="docs-only slice" or the real skip reason.

Close a slice with the generic control-plane path:

apex-manifest close \
  --config=apex.workflow.json \
  --slug=app-123-thing \
  --next="APP-124"

Preview close commands before running them:

apex-manifest close \
  --config=apex.workflow.json \
  --slug=app-123-thing \
  --preview-commands

close runs detect, runs and records required manifest checks, records git diff --check, and prints the finish packet. With dirtyPolicy=owned-files-only, the diff check is scoped to ownedFiles; if no owned files are listed, it records a skipped diff-check entry instead of testing unrelated dirty work. For GitNexus-enabled non-tiny code slices, close also refuses to finish until the freshness gate has pre-slice and post-slice evidence. When required checks are skipped, close refuses stale check evidence unless --allow-stale-evidence="<reason>" is provided and recorded.

Generate a handoff packet from the manifest:

apex-manifest finish \
  --config=apex.workflow.json \
  --slug=app-123-thing \
  --verified="npm test" \
  --skipped="browser: no UI change" \
  --tracker-update="none" \
  --next="APP-124"

Why It Works

• It makes repo authority explicit. The agent reads the right docs before broad search.
• It makes scope tangible. The manifest names owned files, no-touch surfaces, checks, and next slice.
• It prevents overbuilt process. Mode selection lets tiny work stay tiny and shared work get the heavier guardrails it deserves.
• It separates concerns. Product truth, tracker state, graph intelligence, browser evidence, and verification are different systems.
• It supports real-world failure. If MCP breaks, fallback paths are documented instead of pretending the tool is fine.
• It improves handoff quality. Every meaningful pass ends with what landed, what was verified, what was not verified, and what comes next.

Pros And Cons

Pros:

• repeatable install path for agent workflows
• lower resume ambiguity across long-running coding sessions
• cleaner boundaries for multi-agent or dirty-branch work
• fewer broad, ungrounded edits to shared surfaces
• MCP/GitNexus integration without betting everything on one transport
• works across apps because the app profile carries the local truth

Cons:

• requires a profile before the workflow is useful
• adds a manifest step for meaningful code slices
• depends on the target repo having honest docs, tests, and tracker semantics
• auto-detection is useful but not magic; product authority may need review
• GitNexus MCP still depends on the host agent's MCP support unless wrapper fallback is configured

Repository Layout

apex-workflow/
  AGENTS.md                         agent-facing install contract
  README.md                         this landing page
  package.json                      init, manifest, validation scripts
  templates/apex.workflow.json      blank target-app profile
  profiles/minty.workflow.json      extracted production profile
  profiles/service-desk.workflow.json non-Minty example profile
  schemas/apex.workflow.schema.json profile schema
  schemas/apex.manifest.schema.json slice manifest schema
  benchmarks/workflow-fixtures.json workflow benchmark scenarios and thresholds
  scripts/init-harness.mjs          target repo installer
  scripts/apex-doctor.mjs           readiness checker
  scripts/apex-manifest.mjs         slice manifest lifecycle
  scripts/bench-workflow.mjs        no-service workflow outcome benchmark
  scripts/check-config.mjs          profile validator
  scripts/test-installer-fixtures.mjs fixture regression tests
  skills/apex-workflow/SKILL.md     Codex skill entrypoint
  docs/adoption.md                  install details
  docs/extraction-map.md            extraction notes

Local Verification

npm run check:syntax
npm run check:portability
npm run check:config
npm run test:fixtures
npm run test:demo
npm run self-check

self-check is clean-room runnable: it validates the repo-local service-desk fixture and uses temporary fixture repos instead of any private target app. Private app profile validation belongs in guarded scripts such as MINTY_TARGET=/path/to/private/repo npm run check:minty.

Security and outcome checks are separate from the fast local loop:

npm run check:security
npm run check:supply-chain
npm run bench:workflow

The workflow benchmark writes machine-readable output to tmp/apex-workflow/workflow-benchmark.json and fails on scope escapes, missing verification evidence, incomplete finish packets, stale-evidence misses, dirty-branch false failures, or unrecoverable resume state.

Adaptive Repo Profiles

Apex can now inspect a target repo and produce a candidate adaptive profile:

npm run profile -- discover --target=/path/to/app
npm run init -- \
  --target=/path/to/app \
  --config-mode=custom \
  --tracker=file \
  --code-intelligence=focused-search \
  --browser=none \
  --discover \
  --yes

Discovery defaults to operatingModel.default = ledger, disables executor-style command driving by default, records a conditional manifest policy, and infers focused verification presets from repo evidence. Rust focused discovery stays cheap (git diff --check, cargo fmt --check); constrained or broad Cargo checks live in separate escalated presets. The installer does not run discovery unless --discover is passed after explicit adapter choices, and the install report says when discovery was skipped. Use npm run profile -- show --config=apex.workflow.json --target=/path/to/app to inspect the effective operating model, manifest policy, code-intelligence fallback, observation log, and verification presets.

Manifest creation can use explicit presets and slice templates:

npm run manifest -- new --config=apex.workflow.json --slug=build-install --template=build_install --mode=route-local --surface="installer" --files=scripts/install.sh --downshift="ledger: install evidence required"

Local observations are written to tmp/apex-workflow/observations.jsonl when profile discovery is enabled. They stay inside the repo by default and are sanitized before persistence: raw output fields are dropped, long strings are capped, and common token/password/secret/bearer patterns are redacted. Profile recommendations are generated but never applied without an explicit accept step:

npm run profile -- recommend --config=apex.workflow.json --target=/path/to/app
npm run profile -- diff --config=apex.workflow.json --target=/path/to/app
npm run profile -- accept --config=apex.workflow.json --target=/path/to/app --yes

Installer review items can also be accepted explicitly after review, without deleting the original installer note:

npm run profile -- accept-review --config=apex.workflow.json --target=/path/to/app --review="<exact setup.reviewNeeded item>" --yes

Canonical adaptive config uses version and codeIntelligence.provider. apex-check-config accepts the older schemaVersion and codeIntelligence.backend aliases only when they do not conflict, and validates the normalized profile.

License

Apex Workflow is released under the MIT License. The package remains private and is not configured for npm publishing.

The Philosophy

Apex does not try to make agents autonomous by removing process. It makes them effective by giving them the process a senior engineer would enforce anyway: read the repo, choose the smallest safe mode, respect contracts, prove the slice, and leave the next agent a clean trail.