briefops 1.0.0

package/docs/token-budget.md

@@ -0,0 +1,63 @@
+# Token Budget
+
+BriefOps estimates tokens locally and reports section budgets in generated artifacts.
+
+Brief generation uses the final rendered Markdown estimate as `totalTokens`. Inspection calls the same generate path so token reports match generated output.
+
+Handoffs also include section budgets and warnings when generated content exceeds the requested budget.
+
+View the default budget policy:
+
+```bash
+briefops inspect budget
+```
+
+Current targets:
+
+- `AGENTS.md`: 500 tokens
+- `CLAUDE.md`: 700 tokens
+- Cursor rule: 350 tokens
+- Cursor rules total: 1200 tokens
+- prime default: 800 tokens
+- handoff default: 2500 tokens
+- resume pack default: 3000 tokens
+
+`briefops prime` is the smallest start-of-thread artifact. Use it before broad history inspection:
+
+```bash
+briefops prime --task "Continue unresolved checks." --format codex --max-tokens 800
+```
+
+For sharing outside the local machine, use:
+
+```bash
+briefops prime --task "Continue unresolved checks." --export-policy shared-only
+briefops pack resume --worker <worker> --task "Continue unresolved checks." --export-policy shared-only
+```
+
+`shared-only` includes only memory items marked `visibility: shared` and `exportable: true`.
+It omits private memory, local project file details, raw work logs, open risks, local next steps, private worker lessons, private incidents, recent work history, and private metadata counts.
+
+`local-private` is intended for local terminal/Codex use only.
+
+## Compare Context
+
+Use `compare context` to see why BriefOps compiles context instead of dumping history:
+
+```bash
+briefops compare context --worker <worker> --task "Review this PR."
+```
+
+The command estimates local `.briefops` candidate inputs such as project context, worker summary, active memory, and recent logs, then compares them with compiled `briefops prime` output.
+
+## Harness Router Budgets
+
+Harness exports should stay small:
+
+```bash
+briefops export agents-md
+briefops export claude-md
+briefops export cursor-rules
+```
+
+These exports are routers. They include command usage and safety boundaries, not raw memory, logs, decisions, incidents, or handoffs.

package/examples/atlas-q/README.md

@@ -0,0 +1,15 @@
+# Atlas-Q Example
+
+This folder is a tiny placeholder example for the README workflow.
+
+Example BriefOps setup:
+
+```bash
+briefops init
+briefops skill create risk-review --description "Review changes for risk and governance violations" --tags "review,risk,governance"
+briefops project create atlas-q --description "Rule-based non-ML quantitative trading system" --tags "quant,trading"
+briefops memory add --type lessons --project atlas-q --skill risk-review --content "Always verify turnover warning threshold when rebalance logic changes."
+briefops brief generate --skill risk-review --project atlas-q --task "Review recent rebalance logic changes." --budget 2000
+```
+
+The generated brief should include the skill, project context, matching active memory, task, delivery format, source references, and token budget report.

package/examples/codex-first-context/README.md

@@ -0,0 +1,48 @@
+# Codex First Context Example
+
+This example shows the intended BriefOps first-context workflow.
+
+The problem: a fresh Codex thread often spends tokens rediscovering project history, prior decisions, unresolved risks, and worker habits.
+
+The BriefOps path:
+
+```bash
+briefops init
+briefops codex install
+briefops codex plugin install
+briefops skill create risk-review
+briefops project create atlas-q
+briefops worker create quant-reviewer --project atlas-q --skills risk-review
+briefops worker use quant-reviewer
+briefops export agents-md --worker quant-reviewer --force
+briefops prime --task "Continue unresolved slippage checks." --format codex --max-tokens 800
+```
+
+`briefops prime` is intentionally smaller than a handoff or portable resume pack. It selects the smallest useful context for starting work, then points Codex to the next command only when a full continuation pack is actually needed.
+
+`briefops export agents-md` is a router export. It tells Codex how to call BriefOps and keeps private memory, raw logs, handoffs, decisions, incidents, and worker summaries out of `AGENTS.md`.
+
+For portable/shared artifacts:
+
+```bash
+briefops prime --task "Continue unresolved slippage checks." --format codex --export-policy shared-only
+briefops pack resume --worker quant-reviewer --task "Continue unresolved slippage checks." --export-policy shared-only
+```
+
+`shared-only` omits private memory, local project file details, raw work logs, open risks, local next steps, private worker lessons, private incidents, recent work history, and private metadata counts. `local-private` is intended for local terminal/Codex use only.
+
+BriefOps skills must never auto-approve memory proposals or skill patches.
+
+Harnesses such as LazyCodex or OmO can use BriefOps as the first local context ledger before they run their own orchestration. Keep approval human-confirmed: do not let a harness auto-run `briefops approve latest`.
+
+Useful context-minimalism checks:
+
+```bash
+briefops inspect budget
+briefops compare context --worker quant-reviewer --task "Continue unresolved slippage checks."
+```
+
+Files:
+
+- `before-manual-history-dump.md` shows the kind of repeated context users often paste manually.
+- `after-briefops-prime.md` shows the compact shape BriefOps should produce.

package/examples/codex-first-context/after-briefops-prime.md

@@ -0,0 +1,40 @@
+# BriefOps Prime Context
+
+Status: ready
+
+## Token Budget
+
+- Maximum: 800
+- Export policy: local-private
+
+## Current Task
+
+Continue unresolved slippage checks.
+
+## Worker
+
+- Worker: quant-reviewer
+- Project: atlas-q
+- Skills: risk-review
+
+## Continuity Status
+
+- Readiness: PASS
+- Work logs: 8
+
+## Highest-Value Memory
+
+- [lesson] Always verify turnover warning threshold before merge recommendation.
+- [decision] Treat unverified slippage assumptions as blocking.
+
+## Open Risks And Next Steps
+
+Open risks:
+- Slippage assumptions remain unresolved.
+
+Next steps:
+- Verify slippage assumptions against policy.
+
+## Pending User Review
+
+- No pending user review found.

package/examples/codex-first-context/before-manual-history-dump.md

@@ -0,0 +1,18 @@
+# Manual History Dump
+
+Project: atlas-q is a rule-based quantitative trading system.
+
+Worker: quant-reviewer reviews risk and governance before merge recommendations.
+
+Prior notes repeated into fresh threads:
+
+- Always verify turnover warning threshold before recommending merge.
+- Treat unverified slippage assumptions as blocking.
+- Missing turnover warning checks were previously missed during rebalance review.
+- Slippage assumptions remain unresolved until checked against policy.
+- Continue by inspecting risk policy and adding slippage verification to the review checklist.
+- The worker style is skeptical and verification-first.
+- The project does not allow strategy drift without approval.
+- The reviewer should call out unresolved risk explicitly.
+
+This kind of manual context grows quickly as logs, handoffs, and memory files accumulate.

package/examples/persistent-worker-demo/README.md

@@ -0,0 +1,15 @@
+# Persistent Worker Demo
+
+This example shows BriefOps carrying work memory across fresh AI coding threads.
+
+Before: the user pastes repeated project rules, prior decisions, and missed-check lessons into every new thread.
+
+After:
+
+```bash
+briefops codex resume --worker quant-reviewer --task "Continue the rebalance review and identify remaining risks."
+```
+
+The resume prompt includes a compact handoff, worker judgment rules, recent work, active decisions, lessons, incidents, evidence gates, and after-completion logging commands.
+
+The `briefops-workspace/` folder mirrors the important `.briefops/` files for a small atlas-q project.

package/examples/persistent-worker-demo/after-codex-resume.md

@@ -0,0 +1,17 @@
+# After: Codex Resume
+
+Generated with:
+
+```bash
+briefops codex resume --worker quant-reviewer --task "Continue the rebalance review and identify remaining risks." --save
+```
+
+The prompt contains:
+
+- worker summary for `quant-reviewer`
+- active decision: missing universe coverage above 20% stops execution
+- active lesson: verify turnover warning thresholds
+- incident: prior missed turnover warning check
+- recent work history
+- evidence gates
+- after-completion BriefOps commands

package/examples/persistent-worker-demo/before-context-dump.md

@@ -0,0 +1,5 @@
+# Before: Context Dump
+
+We are working on atlas-q, a rule-based quantitative trading system. Remember that missing universe coverage above 20% must stop execution. The reviewer should be skeptical and governance-first. Last time the review missed a turnover warning check, so always verify the turnover warning threshold when rebalance logic changes. Also check slippage and fee assumptions before approving backtest changes.
+
+Please continue the rebalance review and identify remaining risks.

package/examples/persistent-worker-demo/briefops-workspace/codex/prompts/resume_demo.md

@@ -0,0 +1,29 @@
+# BriefOps Codex Resume Mission
+
+## Mission
+
+Continue the rebalance review and identify remaining risks.
+
+## Continuity Contract
+
+1. Read the handoff before making changes.
+2. Treat active decisions as constraints.
+3. Apply worker judgment rules.
+4. Avoid repeating known failure patterns.
+
+## Evidence Gates
+
+- Context gate: list files/docs inspected.
+- Continuity gate: mention which prior decision/lesson influenced the work.
+- Verification gate: include commands or manual checks.
+- Memory gate: state what should be logged or promoted after completion.
+
+## Handoff Brief
+
+See `handoffs/handoff_demo.md`.
+
+## Completion Signal
+
+```text
+<briefops-complete>DONE</briefops-complete>
+```

package/examples/persistent-worker-demo/briefops-workspace/handoffs/handoff_demo.md

@@ -0,0 +1,50 @@
+---
+id: handoff_demo
+created_at: "2026-06-04T00:15:00.000Z"
+project: atlas-q
+worker: quant-reviewer
+task: Continue reviewing rebalance policy changes.
+adapter: codex
+budget: 3000
+total_tokens: 420
+warnings: []
+---
+
+# BriefOps Handoff Brief
+
+## Purpose
+
+This handoff prepares a fresh AI coding thread to continue work without restarting from zero.
+
+## Project
+
+atlas-q is a rule-based non-ML quantitative trading system with governance checks for rebalance and risk policy.
+
+## Worker
+
+Use `quant-reviewer` summary: skeptical, governance-first, verify before completion.
+
+## Recent Work History
+
+- 2026-06-04: Review rebalance logic.; Found missing turnover warning check.
+- 2026-06-04: Review slippage assumptions.; Requested explicit slippage test.
+
+## Active Decisions
+
+- Missing universe coverage above 20% must stop execution.
+
+## Active Lessons
+
+- Always verify turnover warning threshold when rebalance logic changes.
+
+## Known Incidents / Failure Patterns
+
+- Previous review missed turnover warning check.
+
+## After Completion
+
+```bash
+briefops log add ...
+briefops memory propose-from-log latest
+briefops worker refresh-summary quant-reviewer
+```

package/examples/persistent-worker-demo/briefops-workspace/logs/log_20260604_001.yaml

@@ -0,0 +1,14 @@
+id: log_20260604_001
+created_at: "2026-06-04T00:00:00.000Z"
+project: atlas-q
+skill: risk-review
+worker: quant-reviewer
+task: Review rebalance logic.
+result: Found missing turnover warning check.
+lessons:
+  - Always verify turnover warning threshold when rebalance logic changes.
+files_changed:
+  - src/risk/turnover.ts
+commands_run:
+  - npm test
+notes: "decision: Keep rebalance warning thresholds centralized."

package/examples/persistent-worker-demo/briefops-workspace/logs/log_20260604_002.yaml

@@ -0,0 +1,12 @@
+id: log_20260604_002
+created_at: "2026-06-04T01:00:00.000Z"
+project: atlas-q
+skill: backtest-validation
+worker: quant-reviewer
+task: Review slippage assumptions.
+result: Requested explicit slippage test.
+lessons:
+  - Always check slippage and fee assumptions before approving backtest changes.
+files_changed: []
+commands_run: []
+notes: ""

package/examples/persistent-worker-demo/briefops-workspace/memory/decisions.yaml

@@ -0,0 +1,12 @@
+items:
+  - id: mem_demo_decision_001
+    type: decision
+    status: active
+    project: atlas-q
+    skill: risk-review
+    content: Missing universe coverage above 20% must stop execution.
+    source: manual
+    created_at: "2026-06-04T00:00:00.000Z"
+    tags:
+      - universe
+      - governance

package/examples/persistent-worker-demo/briefops-workspace/memory/deprecated.yaml

@@ -0,0 +1 @@
+items: []

package/examples/persistent-worker-demo/briefops-workspace/memory/facts.yaml

@@ -0,0 +1,12 @@
+items:
+  - id: mem_demo_fact_001
+    type: fact
+    status: active
+    project: atlas-q
+    skill: risk-review
+    content: Project uses Vite + React for internal review tools.
+    source: manual
+    created_at: "2026-06-04T00:00:00.000Z"
+    tags:
+      - vite
+      - react

package/examples/persistent-worker-demo/briefops-workspace/memory/incidents.yaml

@@ -0,0 +1,12 @@
+items:
+  - id: mem_demo_incident_001
+    type: incident
+    status: active
+    project: atlas-q
+    skill: risk-review
+    content: Previous review missed turnover warning check.
+    source: proposal:memprop_demo_001
+    created_at: "2026-06-04T00:00:00.000Z"
+    tags:
+      - missed-check
+      - turnover

package/examples/persistent-worker-demo/briefops-workspace/memory/lessons.yaml

@@ -0,0 +1,12 @@
+items:
+  - id: mem_demo_lesson_001
+    type: lesson
+    status: active
+    project: atlas-q
+    skill: risk-review
+    content: Always verify turnover warning threshold when rebalance logic changes.
+    source: proposal:memprop_demo_001
+    created_at: "2026-06-04T00:00:00.000Z"
+    tags:
+      - turnover
+      - rebalance

package/examples/persistent-worker-demo/briefops-workspace/memory-proposals/memprop_demo_001.memory-proposal.yaml

@@ -0,0 +1,23 @@
+id: memprop_demo_001
+created_at: "2026-06-04T00:05:00.000Z"
+from_log: log_20260604_001
+status: applied
+project: atlas-q
+skill: risk-review
+worker: quant-reviewer
+proposals:
+  - type: lesson
+    status: active
+    content: Always verify turnover warning threshold when rebalance logic changes.
+    tags:
+      - turnover
+      - rebalance
+    rationale: Extracted from work log lesson.
+  - type: incident
+    status: active
+    content: Found missing turnover warning check.
+    tags:
+      - turnover
+      - missing
+    rationale: Extracted from work log result.
+applied_at: "2026-06-04T00:06:00.000Z"

package/examples/persistent-worker-demo/briefops-workspace/projects/atlas-q.project.md

@@ -0,0 +1,18 @@
+---
+name: atlas-q
+description: Rule-based non-ML quantitative trading system.
+version: 0.1.0
+tags:
+  - quant
+max_tokens: 500
+---
+
+## Context
+
+atlas-q uses explicit governance checks around rebalance, universe coverage, slippage, and turnover warnings.
+
+## Read If Needed
+
+- src/rebalance/policy.ts
+- src/risk/turnover.ts
+- tests/rebalance-policy.test.ts

package/examples/persistent-worker-demo/briefops-workspace/skills/backtest-validation.skill.md

@@ -0,0 +1,13 @@
+---
+name: backtest-validation
+description: Validate backtest assumptions and reporting.
+version: 0.1.0
+tags:
+  - backtest
+max_tokens: 400
+---
+
+## Protocol
+
+- Check slippage and fee assumptions.
+- Require explicit evidence for changed metrics.

package/examples/persistent-worker-demo/briefops-workspace/skills/risk-review.skill.md

@@ -0,0 +1,15 @@
+---
+name: risk-review
+description: Review quantitative strategy changes for risk and governance violations.
+version: 0.1.0
+tags:
+  - risk
+  - review
+max_tokens: 400
+---
+
+## Protocol
+
+- Check risk-policy enforcement before approving behavior changes.
+- Treat missing risk-policy tests as blocking.
+- Verify turnover warning thresholds when rebalance logic changes.

package/examples/persistent-worker-demo/briefops-workspace/workers/quant-reviewer.worker.yaml

@@ -0,0 +1,12 @@
+name: quant-reviewer
+description: Risk-focused quantitative strategy reviewer.
+project: atlas-q
+default_skills:
+  - risk-review
+  - backtest-validation
+style:
+  - skeptical
+  - governance-first
+  - verify before completion
+max_tokens: 500
+status: active

package/examples/persistent-worker-demo/briefops-workspace/workers/summaries/quant-reviewer.summary.md

@@ -0,0 +1,44 @@
+# Worker Summary: quant-reviewer
+
+## Identity
+
+Risk-focused quantitative strategy reviewer.
+
+## Default Project
+
+atlas-q
+
+## Default Skills
+
+- risk-review
+- backtest-validation
+
+## Operating Style
+
+- skeptical
+- governance-first
+- verify before completion
+
+## Recent Work
+
+- 2026-06-04: Review rebalance logic.; Found missing turnover warning check.
+- 2026-06-04: Review slippage assumptions.; Requested explicit slippage test.
+
+## Accumulated Lessons
+
+- Always verify turnover warning threshold when rebalance logic changes.
+- Always check slippage and fee assumptions before approving backtest changes.
+
+## Known Failure Patterns
+
+- Previous review missed turnover warning check.
+
+## Active Judgment Rules
+
+- Reject unverified behavior changes.
+- Require explicit approval for strategy drift.
+- Treat missing risk-policy tests as blocking.
+
+## Last Refreshed
+
+2026-06-04T00:10:00.000Z

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "briefops",
+  "version": "1.0.0",
+  "description": "Local-first, token-aware skill and briefing layer for AI coding agents.",
+  "type": "module",
+  "bin": {
+    "briefops": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "dev": "tsx src/index.ts",
+    "verify:release": "npm run build && npm test && npm audit --audit-level=moderate && npm pack --dry-run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/simony-816/briefops.git"
+  },
+  "bugs": {
+    "url": "https://github.com/simony-816/briefops/issues"
+  },
+  "homepage": "https://github.com/simony-816/briefops#readme",
+  "keywords": [
+    "codex",
+    "ai-agents",
+    "local-first",
+    "memory",
+    "context",
+    "handoff",
+    "developer-tools"
+  ],
+  "dependencies": {
+    "commander": "^12.1.0",
+    "yaml": "^2.5.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.5",
+    "tsx": "^4.19.1",
+    "typescript": "^5.6.2",
+    "vitest": "^4.1.8"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "plugins",
+    "examples",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md",
+    "CHANGELOG.md"
+  ],
+  "license": "MIT"
+}

package/plugins/briefops-codex/.codex-plugin/plugin.json

@@ -0,0 +1,39 @@
+{
+  "name": "briefops",
+  "version": "1.0.0",
+  "description": "Local-first, token-aware persistent work history for Codex workflows.",
+  "author": {
+    "name": "BriefOps contributors",
+    "url": "https://github.com/simony-816/briefops"
+  },
+  "homepage": "https://github.com/simony-816/briefops",
+  "repository": "https://github.com/simony-816/briefops",
+  "license": "MIT",
+  "keywords": [
+    "codex",
+    "local-first",
+    "context",
+    "memory",
+    "handoff",
+    "workflow"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "BriefOps",
+    "shortDescription": "local-first context priming and continuity for Codex",
+    "longDescription": "Use BriefOps to prime Codex with compact local context, record task outcomes, review durable memory proposals, and resume persistent workers without hosted services.",
+    "developerName": "BriefOps contributors",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Read",
+      "Write"
+    ],
+    "defaultPrompt": [
+      "Start this task with the smallest useful BriefOps context.",
+      "Finish this task and prepare memory for the next thread."
+    ],
+    "websiteURL": "https://github.com/simony-816/briefops",
+    "brandColor": "#2563EB",
+    "screenshots": []
+  }
+}

package/plugins/briefops-codex/README.md

@@ -0,0 +1,44 @@
+# BriefOps Codex Plugin
+
+This is a skill-only Codex plugin bundle for BriefOps.
+
+It does not run a hosted service and does not sync data. The skills call the local `briefops` CLI and local `.briefops/` workspace.
+It does not publish to a marketplace and does not write to global Codex folders by default.
+
+The BriefOps plugin is a local CLI helper. It does not require network access, does not publish to a marketplace, and should not auto-approve memory or skill patches. Use `--export-policy shared-only` before copying context outside the local workspace.
+
+Recommended local setup:
+
+```bash
+briefops init
+briefops codex install
+briefops codex plugin install
+briefops worker use <worker>
+briefops prime --task "Start this task." --format codex
+```
+
+The generated local plugin copy is written to:
+
+```text
+.briefops/codex/plugin/briefops
+```
+
+BriefOps plugin skills must never auto-approve memory proposals or skill patches.
+
+For repo-level harness guidance, generate router files:
+
+```bash
+briefops export agents-md
+briefops export all
+```
+
+These exports route local harnesses back to `briefops prime`, `briefops finish`, `briefops approve`, and `briefops continue --pack`. They do not copy `.briefops` memory, logs, handoffs, or worker summaries.
+
+Use shared-only exports for portable context:
+
+```bash
+briefops prime --task "Start this task." --format codex --export-policy shared-only
+briefops pack resume --worker <worker> --task "Start this task." --export-policy shared-only
+```
+
+`shared-only` omits private memory, local project file details, raw work logs, open risks, local next steps, private worker lessons, private incidents, recent work history, and private metadata counts.