feat(flow): add codex control-plane workflows

Add centralized Flow config/extensions, bounded project-ai and ops visibility, PR/session-doc packets, and sturdier JJ/sync workflow helpers. Keep the public repo clean by stripping Prom-specific staging leaks before commit.

Author: nikivdev

docs/codex-fork-tasks.md

@@ -97,14 +97,14 @@ Creates or updates a review branch from the current task worktree tip.
 
 Default mapping:
 
-- `codex/workspace-awareness` -> `review/nikiv-workspace-awareness`
+- `codex/workspace-awareness` -> `review/workspace-awareness`
 
 Examples:
 
 ```bash
 f codex-fork-promote
 f codex-fork-promote codex/workspace-awareness --push
-f codex-fork-promote ~/.worktrees/codex/codex-workspace-awareness --review-branch review/nikiv-codex-workspace-awareness
+f codex-fork-promote ~/.worktrees/codex/codex-workspace-awareness --review-branch review/workspace-awareness
 ```
 
 ## State File

docs/commands/ai.md

@@ -21,6 +21,8 @@ f ai cursor list
 f codex resolve "latest"
 f codex resolve "https://linear.app/.../project/.../overview" --json
 f codex open "continue the deploy work"
+f codex agent list
+f codex agent show commit
 f ai claude resume <session-id-or-name>
 f ai codex resume <session-id-or-name>
 f ai codex resume --path ~/work/example-project
@@ -132,6 +134,7 @@ You can teach `f codex open` and `f codex resolve` to unroll repo-specific refer
 auto_resolve_references = true
 prompt_context_budget_chars = 900
 max_resolved_references = 1
+sync_workflow_command = "./scripts/sync-safe"
 
 [[codex.reference_resolver]]
 name = "linear"
@@ -148,6 +151,7 @@ Notes:
 - resolver output is compacted before prompt injection
 - `prompt_context_budget_chars` hard-caps injected context before your request is appended
 - `max_resolved_references` prevents broad unrolling from bloating one turn
+- `sync_workflow_command` lets plain `sync branch` route into a repo-specific safe sync command instead of improvised Git/JJ steps
 
 ### Optional runtime skill transport
 
@@ -170,6 +174,26 @@ runtime_skills = true
 codex_bin = "~/code/flow/scripts/codex-flow-wrapper"
 ```
 
+For the `~/code/flow` repo specifically, the intended in-repo shape is:
+
+```toml
+[options]
+codex_bin = "~/code/flow/scripts/codex-flow-wrapper"
+
+[codex]
+runtime_skills = true
+auto_resolve_references = true
+prompt_context_budget_chars = 1200
+max_resolved_references = 2
+
+[[codex.skill_source]]
+name = "run-control-plane"
+path = "~/run"
+enabled = true
+```
+
+That keeps a fresh checkout Codex-first even before machine-local setup is remembered.
+
 Current first-slice behavior:
 
 - `f codex open "write plan"` can attach a tiny plan-writing runtime skill
@@ -210,6 +234,41 @@ cat <<'EOF' | f codex runtime write-plan --title "Example Plan"
 EOF
 ```
 
+By default this writes to today's `~/plan/<day-of-month>/` bucket, for example
+`~/plan/23/` on the 23rd day of the month.
+
+### Run-owned agent bridge
+
+Flow can execute run-owned Codex agents directly without copying their specs or
+prompts into `~/code/flow`.
+
+Useful commands:
+
+```bash
+f codex agent list
+f codex agent list --json
+f codex agent show commit
+f codex agent run planner --path ~/code/flow "make a 3 phase rollout plan"
+f codex agent run commit --path ~/repos/openai/codex "review the current diff and draft a safe commit"
+f codex agent run planner --json --path ~/code/flow "reply with exactly: ok"
+```
+
+Behavior:
+
+- Flow bridges into `~/run/scripts/agent-router.sh`
+- the run-owned agent still executes through its own spec/runtime path in `~/run`
+- `--path` controls the repo/worktree cwd used for the agent run
+- `run` returns the agent's final output plus any durable artifact/trace paths
+- `f codex doctor --path <repo>` reports whether the run-agent bridge is ready
+
+Repo-local readiness check:
+
+```bash
+f codex doctor --path ~/code/flow --assert-runtime --assert-schedule
+f codex skill-source list --path ~/code/flow
+f codex agent list
+```
+
 ### Skill eval and background refresh
 
 Flow can learn which runtime skills are actually worth injecting from local
@@ -229,8 +288,12 @@ f codex telemetry flush --limit 200
 f codex trace status
 f codex trace current-session --json
 f codex trace inspect <trace-id> --json
+f codex project-ai show --path ~/work/example-project --json
+f codex project-ai recent --limit 12 --json
 f codex skill-source list --path ~/work/example-project
 f codex skill-source sync --path ~/work/example-project --skill find-skills
+f codex agent list
+f codex agent run planner --path ~/work/example-project "summarize the next rollout slice"
 ```
 
 The Codex memory mirror:
@@ -243,6 +306,13 @@ The Codex memory mirror:
 - adds tiny symbol snippets for the top code hits, so coding prompts can carry actual struct/function shape without inlining whole files
 - biases retrieval by intent: implementation/file-edit prompts prefer symbols, snippets, and `src/...` paths; summary/docs prompts prefer doc headings and docs paths
 - stays best-effort so failed memory writes do not block normal Codex coding turns
+
+The project-ai manifest:
+
+- gives `codexd` a bounded metadata view of repo-local `.ai/` scaffolding
+- records counts and latest paths for skills, docs, reviews, tasks, and todos
+- keeps default context fill minimal by exposing only compact hints, not raw content
+- tracks query counts and recent repo usage so you can see whether the feature is actually being used
 - is refreshed again by `f codex skill-eval cron`, so the mirror heals even if a hot-path write is skipped
 - is queried automatically for explicit repo references during `f codex open` / `f codex resolve`
 

docs/commands/config.md

@@ -0,0 +1,96 @@
+# f config
+
+Compile the personal Flow root config and generated compatibility outputs.
+
+Source of truth:
+
+- `~/.flow/config.ts`
+
+Generated outputs:
+
+- `~/.config/flow/generated/config.snapshot.json`
+- `~/.config/flow/generated/flow/config.ts`
+- `~/.config/flow/generated/lin/config.ts`
+- `~/.config/flow/generated/lin/intents.json`
+- `~/.config/flow/generated/lin/mac.toml`
+- `~/.config/flow/generated/ai/config.json`
+- `~/.config/flow/generated/hive/config.json`
+
+If `~/.flow/config.ts` does not exist yet, Flow currently falls back to:
+
+- `~/config/i/lin/config.ts`
+
+and generates a starter `~/.flow/config.ts` migration file on apply.
+
+## Commands
+
+### f config doctor
+
+Shows whether the root config exists, whether a TypeScript runner is available,
+whether a generated snapshot already exists, and what extension directories are discoverable.
+
+```bash
+f config doctor
+f config doctor --json
+```
+
+### f config build
+
+Loads the root config plus named extensions, computes the merged effective config,
+and writes generated artifacts under `~/.config/flow/generated/`.
+
+This does not overwrite consumer config locations.
+
+```bash
+f config build
+f config build --json
+```
+
+### f config apply
+
+Builds the snapshot and then applies the generated compatibility files into their
+consumer locations. This is the cutover step that keeps existing tools working while
+moving authoring into `~/.flow/config.ts`.
+
+```bash
+f config apply
+f config apply --json
+```
+
+### f config eval
+
+Prints the currently effective merged config view. If no snapshot exists yet, Flow
+builds one first.
+
+```bash
+f config eval
+f config eval --json
+```
+
+## Root Config Shape
+
+The first supported root-config shape is:
+
+```ts
+export default {
+  flow: { ... },
+  lin: { ... },
+  ai: { ... },
+  hive: { ... },
+  zerg: { ... },
+  extensions: ["lin-compat"],
+}
+```
+
+Filesystem extensions can live under:
+
+- `~/.flow/extensions/<name>/extension.ts`
+- `~/.flow/extensions/<name>/config.ts`
+
+Each extension can contribute partial config fragments plus optional generated files.
+
+## Notes
+
+- Flow currently ships one built-in extension name: `lin-compat`
+- explicit extensions must exist or `f config build` fails
+- generated outputs are written atomically

docs/commands/docs.md

@@ -70,6 +70,42 @@ Lists `.ai/docs` files for the current project.
 
 Shows recent commits and `.ai/docs` file modification times.
 
+It now also shows:
+
+- recent `.ai/docs/session-changes/...` packets generated from completed Flow-managed Codex sessions
+- doc-review queue state counts for the current project
+
+### f docs review-pending
+
+Runs the bounded daemon-style review pass over pending session-doc packets and records
+promotion decisions into queue state plus each packet's `promotion.json`.
+
+Options:
+
+- `-n, --limit <N>`: Maximum number of pending entries to review (default: `25`).
+
+### f docs promote-session
+
+Previews or applies promotion for a daemon-captured session-doc packet.
+
+By default this is a dry run. It prints the chosen target under `.ai/docs/` and the
+promoted markdown note.
+
+Options:
+
+- `<SESSION>`: Session id, session id prefix, or session key like `019d035d-...` or `019d035d-1773776290`
+- `--apply`: Write the promoted note immediately
+
+### f docs commit-pending
+
+Commits promoted session-doc notes when the git diff is isolated to doc-only files.
+
+This command refuses to commit if the worktree contains unrelated changes.
+
+Options:
+
+- `--dry-run`: Show the candidate files and commit message without staging or committing
+
 ### f docs edit
 
 Opens a `.ai/docs` file in `$EDITOR`.

docs/commands/ext.md

@@ -0,0 +1,121 @@
+# f ext
+
+Manage Flow config extensions under `~/.flow/extensions`.
+
+This is the extension/operator surface for the centralized Flow config system:
+
+- root config: `~/.flow/config.ts`
+- runtime helper: `~/.flow/runtime/flow-config.ts`
+- extension root: `~/.flow/extensions/<name>/`
+
+Extensions are loaded by `f config build` / `f config apply` when their names
+appear in `extensions: [...]` inside `~/.flow/config.ts`.
+
+For backwards compatibility, `f ext <path>` still supports the older external
+directory import workflow into `<project>/ext/<name>`.
+
+## Commands
+
+### f ext list
+
+List built-in and filesystem extensions and whether they are enabled.
+
+```bash
+f ext list
+f ext list --json
+```
+
+### f ext doctor
+
+Show root-config wiring for extensions:
+
+- `~/.flow/config.ts`
+- `~/.flow/extensions`
+- `~/.flow/runtime/flow-config.ts`
+
+and the currently discoverable extensions.
+
+```bash
+f ext doctor
+f ext doctor --json
+```
+
+### f ext init
+
+Create a new extension scaffold under `~/.flow/extensions/<name>/`.
+
+Generated files:
+
+- `extension.ts`
+- `README.md`
+
+The scaffold imports:
+
+- `defineFlowExtension` from `~/.flow/runtime/flow-config.ts`
+
+```bash
+f ext init my-extension
+f ext init my-extension --force
+```
+
+### f ext enable
+
+Enable an extension by name in `~/.flow/config.ts`.
+
+```bash
+f ext enable my-extension
+```
+
+### f ext disable
+
+Disable an extension by name in `~/.flow/config.ts`.
+
+```bash
+f ext disable my-extension
+```
+
+### f ext import
+
+Explicit legacy import form. Copies an external directory into `<project>/ext/`
+and adds `ext/` to `.gitignore`.
+
+```bash
+f ext import ~/some/external/repo
+```
+
+Bare path form is still accepted:
+
+```bash
+f ext ~/some/external/repo
+```
+
+## Extension Shape
+
+An extension file can export:
+
+```ts
+import { defineFlowExtension } from "../../runtime/flow-config"
+
+export default defineFlowExtension({
+  name: "my-extension",
+  flow: { ... },
+  lin: { ... },
+  ai: { ... },
+  hive: { ... },
+  zerg: { ... },
+  generatedFiles: [
+    {
+      path: "~/.some/target/file.json",
+      content: "{...}",
+    },
+  ],
+  doctor: ["human-readable check or note"],
+})
+```
+
+## Notes
+
+- built-in extension currently supported: `lin-compat`
+- `f ext enable` rewrites `~/.flow/config.ts`
+- `f ext init` also ensures the runtime helper exists
+- generated file path collisions fail the build