Ops Framework

Reusable human-in-the-loop delivery framework for planning, checking, executing and verifying software tasks across separate project repositories.

The package owns the process engine and reusable assets. Each project owns its task history, memory, cache, project playbook overlays and local provider overrides.

What Lives In The Package

• bin/: CLI commands and shared implementation utilities.
• prompts/: reusable agent prompts for supervisor, researcher, planner, checker, executor and verifier.
• templates/: task artifact templates.
• playbooks/: shared reusable procedures for UI acceptance, complexity, rollout, provider/source-sync and checker context.
• config/default-agents.json: portable defaults with environment placeholders, not local machine paths.

What Stays In Each Project

• ops/project.ops.yaml: project binding file.
• ops/agent-pipeline/tasks/: task artifacts and history.
• ops/agent-pipeline/memory/: project memory.
• ops/agent-pipeline/playbooks/: project playbook overlays with project-specific routes, commands, services, environments and provider quirks.
• ops/agent-pipeline/cache/: project-local generated cache.
• ops/agent-pipeline/config/agents.json: optional project/user provider override.
• Project-specific deferred work, SQL, runtime notes and learning candidates.

Do not put project memory, task history, secrets, project-specific paths, project service names, routes, provider names or local absolute provider paths into this shared package unless they are explicitly marked as generic examples.

Layer Model

Ops Framework has three layers:

• Shared framework core: CLI, lifecycle, prompts, templates, config defaults and generic gates.
• Shared playbooks: reusable procedures that apply across projects.
• Project overlays: project memory, project playbooks, tasks, cache, local providers and runtime commands.

When a task has relevant risk triggers, checker/verifier context can include both layers:

Shared Playbook: UI Acceptance
Project Overlay: UI Acceptance

Shared playbooks stay portable. Project overlays add concrete routes, commands, services, environments and known project quirks.

Project Config

The recommended setup is:

corepack yarn dlx @besales/ops-framework@latest init --project-name ExampleProject --install-scripts

This creates the project-owned ops/** structure, including ops/project.ops.yaml, task roots, cache, memory files and project-local agent config. With --install-scripts, it also writes package-manager scripts that call the installed ops-agent bin and pins the framework package in devDependencies.

The generated scripts look like:

{
  "scripts": {
    "ops": "ops-agent",
    "agent:run-check": "ops-agent run-check",
    "agent:run-verify": "ops-agent run-verify"
  },
  "devDependencies": {
    "@besales/ops-framework": "0.1.0"
  }
}

Use --framework-version 0.1.0 to pin a specific version, or --framework-package @scope/name for a different registry package name.

The generated ops/project.ops.yaml shape is:

name: ExampleProject
ops:
  legacyPipelineDir: ops/agent-pipeline
  tasksDir: ops/agent-pipeline/tasks
  memoryDir: ops/agent-pipeline/memory
  playbooksDir: ops/agent-pipeline/playbooks
  cacheDir: ops/agent-pipeline/cache
agents:
  configFile: ops/agent-pipeline/config/agents.json
risk:
  uiRoots:
    - apps/web
  backendRoots:
    - apps/api
  workerRoots:
    - apps/workers

ops-agent walks upward from the current working directory until it finds ops/project.ops.yaml.

It then resolves:

• project artifacts from the configured project paths;
• framework prompts/templates/config from this package;
• shared playbooks from the package and project playbook overlays from ops.playbooksDir;
• project provider overrides from agents.configFile, if present.

Risk roots are project-owned. They decide when generic triggers such as UI, user-visible API, worker, production or performance gates apply. Do not hardcode one project's app layout into shared playbooks or shared risk classification.

Fresh bootstrap projects start with commented placeholder root examples. Until a project fills them, build-check-context and preflight warn that path-based UI/API/worker detection is disabled or limited.

If no project config exists, the resolver falls back to a legacy ops/agent-pipeline layout when it can find one.

Optimization Gate

Optimization is built into the normal Plan -> Check -> Execute -> Verify flow, but it is bounded by risk tier so delivery stays fast:

• O0: no dedicated optimization section.
• O1: normal implementation checklist.
• O2: one focused review for touched UI/API/read-model hot paths.
• O3: one focused review plus one representative measurement for workers, materializers, source-sync/provider or production-runtime hot paths.

For O2/O3 work, plan.md must include ## Optimization Strategy with tier, hot paths, expected data size, chosen efficient approach, avoided anti-patterns and a stop rule. execution.md must then include ## Optimization Review Evidence before Verify can pass.

The framework blocks obvious inefficiency early, but speculative or broad optimization ideas should be deferred instead of expanding the task.

CLI

From a project root, run commands through the package entry point:

ops-agent init --project-name ExampleProject --install-scripts
ops-agent new-task TASK-001-example --title "Example task"
ops-agent manifest TASK-001-example
ops-agent preflight TASK-001-example --target execute
ops-agent build-check-context TASK-001-example
ops-agent run-check TASK-001-example
ops-agent run-verify TASK-001-example

When installed as a package, the intended command is:

ops-agent init --project-name ExampleProject
ops-agent new-task TASK-001-example --title "Example task"
ops-agent manifest TASK-001-example

For local package development in another project, use a file: dependency:

{
  "devDependencies": {
    "@besales/ops-framework": "file:../shared-platform/packages/ops-framework"
  }
}

Do not commit that file: dependency to production projects. It is only for package development because production builders usually do not have a sibling ../shared-platform checkout.

Supported Commands

• init
• new-task
• manifest
• preflight
• transition
• build-check-context
• validate-check-artifacts
• estimate-llm-input
• quality-gates
• run-check
• run-verify
• hash-task-artifacts
• build-execution-ledger
• task-metrics
• run-plan-check-loop
• supervisor-turn
• intake-feedback
• intake-execution-feedback
• guard-task
• memory-candidates
• learning-index
• learning-review
• update-memory
• learning-audit
• learning-report
• learning-closeout
• closeout
• initiative-create
• initiative-add-work-package
• initiative-status
• initiative-next
• initiative-intake
• initiative-requirements
• test/self-test

Review Budgets

External run-check and run-verify are bounded by default:

• stage SLA: 180000ms;
• max external provider runs per stage: 1.
• external provider timeout: 180000ms.

When the budget is exceeded, the framework writes human_arbitration_required instead of starting another provider loop. Consolidate the remaining findings in task artifacts, or rerun with --force-review-budget only after explicit human approval recorded in review-budget-approval.json:

{
  "approved": true,
  "stage": "check",
  "reason": "Human approved one extra external review after consolidated remediation.",
  "approvedBy": "human",
  "expiresAt": "2026-06-05T12:00:00.000Z"
}

Learning Loop

Learning is controlled and human-approved:

retrospective/feedback/check/verify artifacts
 -> memory/playbook candidates
 -> learning index
 -> human promote/defer/reject
 -> update memory/playbooks

Use:

ops-agent memory-candidates
ops-agent learning-index
ops-agent learning-review
ops-agent learning-audit
ops-agent update-memory --apply-approved
ops-agent learning-report
ops-agent learning-closeout TASK-001-example
ops-agent closeout TASK-001-example

memory-candidates creates structured learning cards with source, reason hash, learning layer, confidence, problem, lesson, repeat risk, proposed wording and suggested target. learning-index turns those cards into human-reviewable decisions. update-memory only writes approved entries when --apply-approved is passed.

learning-review writes ops/agent-pipeline/memory/learning-review.md, a human approval pack with each pending candidate and the allowed decisions: promote, defer, reject or rewrite.

learning-report writes ops/agent-pipeline/memory/learning-report.md. Show the review pack before approval and the report during closeout so the human can see what the framework learned, what is still pending, and which approved entries were written to project memory or project playbooks.

learning-closeout <TASK> is the default closeout checkpoint after retrospective. It collects candidates from that task, refreshes learning-index.json, writes learning-review.md, writes learning-report.md, creates learning-closeout.md inside the task and updates status.md so human approval is visible. The review must show every learning candidate individually with summary, target, source artifact, reason, proposed change, scope, confidence, promotion risk and the current decision.

closeout <TASK> is the Supervisor entrypoint before any final closure. It validates verify.result.json and retrospective.md, automatically runs learning-closeout <TASK>, pauses when learning decisions are still pending or rewrite, and after --apply-approved applies approved learning, refreshes the report and runs the final guard unless --skip-guard is passed.

Shared playbook candidates are intentionally manual-review only. Promote them through a separate reviewed framework task, not by auto-writing project-specific observations into the shared package.

Initiative Framework

Initiatives are the program-level layer above tasks. Use them for MVPs, large feature trains and multi-phase functionality where a one-task-at-a-time flow would be too slow.

ops-agent initiative-create delivery-os-mvp --title "Delivery OS MVP" --mode fast_mvp
ops-agent initiative-add-work-package delivery-os-mvp WP-001-foundation --title "Foundation"
ops-agent initiative-intake delivery-os-mvp docs/delivery-os --phase phase-1 --include "06-roadmap.md,04-data-model.md,11-tooling-and-data-flows.md"
ops-agent initiative-requirements delivery-os-mvp --phase phase-1
ops-agent initiative-requirements-synthesis delivery-os-mvp
ops-agent initiative-status delivery-os-mvp
ops-agent initiative-next delivery-os-mvp --materialize-task

The hierarchy is:

Initiative
 -> Work-package task
      -> Execution slices inside plan.md/execution.md

Work packages are materialized as normal tasks, so brief/research/plan/check/execute/verify/retrospective/learning still works at the audit boundary. Slices are not separate tasks; they use fast execution, micro-verify and slice evidence inside the work-package task. Create a separate task only when a slice triggers scope, risk, architecture or human-approval escalation.

Work packages can declare Depends on, Unblocks, Can run parallel with and Sequencing notes. initiative-next uses Depends on to avoid materializing a package before required packages are completed. If a work package lists REQ-* coverage, its Acceptance must include requirement-level done criteria or explicit REQ-* acceptance references; process-only acceptance blocks materialization.

For source docs, use intake before work-package planning:

Raw docs
 -> initiative intake/source-index
 -> requirements-map.md
 -> work packages
 -> tasks

initiative-intake <initiative> <docs-dir> indexes supported source documents, writes source SHA hashes and deterministic requirement candidates into intake/. Use --include "file-a.md,file-b.md" to restrict the first pass to the most relevant source files, and --phase phase-1 to keep candidates whose local heading/source context matches the target phase. When --include is used, detected relevant docs such as feedback, skills, profiles, ADRs and risk/governance docs are auto-included by default; pass --no-include-relevant only when intentionally running a narrow diagnostic pass.

initiative-requirements <initiative> turns those candidates into REQ-* rows in requirements-map.md, writes requirements-review.md approval cards and writes coverage.md. Human review is still required before treating candidates as approved or planned.

initiative-requirements-synthesis <initiative> writes requirements-synthesis.md: the human/LLM synthesis pack for converting raw candidates into clean requirements with acceptance criteria. It highlights source coverage gaps, fragments, table rows, run-on blocks and candidate assumptions/questions that must be rewritten before planning. It also runs synthesis readiness gates for missing critical concepts, ADR/NFR coverage, scope/storage conflicts, apply-contract ambiguity, sequencing hints and weak source references.

Feedback Intake

Feedback is stage-agnostic. Any user question, correction, review note or learning observation during an active task should be captured before it is acted on:

ops-agent intake-feedback TASK-001-example "Feedback text"

This appends a classified event to feedback.md, updates status.md, appends orchestration-log.md and makes the event available to checker/verifier context and learning candidates.

Use learning_capture for process/memory/playbook observations that should feed retrospective without invalidating the current implementation scope.

For active task conversations, prefer the turn router:

ops-agent supervisor-turn TASK-001-example "User message"

It records the message, appends a supervisor_turn log event and prints the mandatory response contract:

TASK: ...
STAGE: ...
SUPERVISOR: active
FEEDBACK INTAKE: recorded (...)
ALLOWED NOW: ...
NOT ALLOWED NOW: ...
Следующий шаг: ...

Provider Config

Shared defaults use environment placeholders:

• CODEX_CLI_COMMAND
• CLAUDE_CLI_COMMAND
• CLOUD_CLI_COMMAND
• CHECKER_CLI_COMMAND

Project-local overrides may point to real local binaries in the project or user environment. Keep those overrides out of shared defaults.

Verification Model

The normal lifecycle is:

Brief -> Research -> Plan -> Check -> Human Gate -> Execute -> Verify

Check reviews the plan before implementation. Verify reviews the result after execution evidence exists.

Internal supervisor verify is acceptable for ordinary local engineering slices. External CLI verify should be used for production readiness, destructive or security-sensitive work, material data migrations/backfills, broad ambiguous refactors or explicit human request.

Release

@besales/ops-framework is published as a public scoped npm package through GitHub Actions trusted publishing.

The release workflow is .github/workflows/publish-ops-framework.yml.

Required npm trusted publisher configuration:

• Package: @besales/ops-framework
• Provider: GitHub Actions
• Organization / user: be-sales
• Repository: shared-platform
• Workflow filename: publish-ops-framework.yml
• Environment: leave empty
• Allowed action: npm publish

The workflow uses GitHub OIDC (id-token: write) and does not require an NPM_TOKEN secret.

For first-time package creation, npm requires the package to exist before a trusted publisher can be attached. Bootstrap the first version with a short-lived manual publish path, configure the trusted publisher, then use the workflow for all future versions.

Manual workflow release:

gh workflow run publish-ops-framework.yml --repo be-sales/shared-platform -f version=0.1.0

Tag workflow release:

git tag ops-framework-v0.1.0
git push origin ops-framework-v0.1.0

Validation

Run package tests:

yarn workspace @besales/ops-framework test

Run package lint:

node bin/self-lint.mjs

Auto-fix supported whitespace issues:

node bin/self-lint.mjs --fix

The lint script checks:

• no .DS_Store files;
• no open-work markers in package files;
• no local home-directory or application-bundle absolute paths in shared files;
• no known project-specific paths or project names in shared files;
• no trailing whitespace;
• text files end with a newline.

Pilot Status

This package was first extracted from a project-local Ops Framework. Pilot task history, memory and provider paths remain project-owned and are connected through that project's ops/project.ops.yaml.