# Alexago83 Cdx Logics Kit Logics Flow Manager

> Logics flow

- Skill: `tomevault-io/alexago83-cdx-logics-kit-logics-flow-manager` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/alexago83-cdx-logics-kit-logics-flow-manager`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/alexago83-cdx-logics-kit-logics-flow-manager/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/alexago83-cdx-logics-kit-logics-flow-manager

---


# Logics flow

## Conventions

- Keep workflow docs in `logics/request/`, `logics/backlog/`, `logics/tasks/`.
- Use companion docs in `logics/product/` for structuring product framing and `logics/architecture/` for structuring technical decisions.
- Use numeric IDs and slugs in filenames: `req_001_my_title.md`, `item_002_some_scope.md`, `task_003_do_the_work.md`.
- When mentioning files in generated docs, use repo-relative paths such as `logics/...` or `src/...`, never absolute filesystem paths such as `/Users/...`.
- Keep indicators at the top:
  - `From version: X.X.X`
  - `Status: Draft | Ready | In progress | Blocked | Done | Obsolete | Archived`
  - `Understanding: ??%`
  - `Confidence: ??%`
  - `Progress: ??%` (mainly tasks; optionally backlog)
  - `Complexity: Low | Medium | High`
  - `Theme: Combat | Items | Economy | UI | ...`
- When writing a request, the `# Context` section must include a Mermaid diagram that visualizes the need.
- Prefer a compact business-readable `flowchart TD` or `flowchart LR` showing inputs, decision points, outputs, and feedback loops.
- Backlog items should include a Mermaid diagram that makes the delivery slice explicit: request/source -> problem -> scope -> acceptance criteria -> task(s).
- Tasks should include a Mermaid diagram that shows the execution path: backlog/source -> implementation steps -> validation -> done/report.
- Generated workflow Mermaid blocks now include `%% logics-signature: ...` metadata comments; keep them aligned with the current doc context so stale diagrams can be detected automatically.
- Mermaid safety rules are mandatory:
  - use plain ASCII text labels only
  - do not use Markdown formatting inside node labels: no backticks, bold, italics, or inline code
  - do not put raw route syntax or braces in labels such as `/users/{id}`; rewrite them as plain text like `users-id route`
  - do not use `+` to concatenate task names inside labels; rewrite as plain text such as `task 1 and task 2`
  - keep labels short and business-readable so strict Mermaid renderers can display them consistently

If unsure, open `logics/instructions.md` and follow the workflow described there.

Command examples below use `python ...` as the canonical cross-platform launcher.
The preferred stable entrypoint is now `python logics/skills/logics.py ...`, which routes toward the flow manager and adjacent kit commands behind one operator-facing contract.
If your environment only exposes `python3` or `py -3`, substitute that launcher.

## Create a new doc (recommended)

Use the generator script (picks the next available ID, creates a file from templates):

```bash
python logics/skills/logics.py flow new request --title "Offline recap UI"
python logics/skills/logics.py flow new request --title "Offline recap UI" --fixture
python logics/skills/logics.py flow new backlog --title "Offline recap UI"
python logics/skills/logics.py flow new task --title "Implement offline recap UI"
```

After creation, run **logics-confidence-booster** to raise Understanding/Confidence above 90%:

```bash
python logics/skills/logics-confidence-booster/scripts/boost_confidence.py logics/request/req_001_example.md
python logics/skills/logics-confidence-booster/scripts/boost_confidence.py logics/backlog/item_002_example.md
python logics/skills/logics-confidence-booster/scripts/boost_confidence.py logics/tasks/task_003_example.md
```

When a request or backlog item surfaces a structuring product choice, create a product brief before or alongside promotion:

```bash
python logics/skills/logics-product-brief-writer/scripts/new_product_brief.py --title "Guest checkout framing" --out-dir logics/product
```

When a backlog item surfaces a structuring technical choice, create an ADR/DAT:

```bash
python logics/skills/logics-architecture-decision-writer/scripts/new_adr.py --title "Choose cache strategy" --out-dir logics/architecture
```

For backlog/task creation or promotion, the script now auto-detects product and architecture signals and writes a `# Decision framing` section in generated docs. It stays advisory by default and can auto-create the companion docs when you opt in:

```bash
python logics/skills/logics.py flow new backlog --title "Checkout auth migration" --auto-create-product-brief --auto-create-adr
```

Optional flags:

- `--from-version 0.14.3`
- `--understanding 60% --confidence 40%`
- `--status Draft|Ready|In progress|Blocked|Done|Obsolete|Archived`
- `--complexity Low|Medium|High --theme UI`
- `--progress 0%` (task/backlog)
- `--fixture` or `--smoke-test` (request only; generate a compact synthetic request shape)
- `--auto-create-product-brief` (backlog/task only; create `logics/product/prod_###_*.md` when product framing is required)
- `--auto-create-adr` (backlog/task only; create `logics/architecture/adr_###_*.md` when architecture framing is required)
- `--dry-run` (show path + content preview, no writes)

## Promote between stages

Create the next-stage doc and link back to the source:

```bash
python logics/skills/logics.py flow promote request-to-backlog logics/request/req_001_offline_recap_ui.md
python logics/skills/logics.py flow promote backlog-to-task logics/backlog/item_002_offline_recap_ui.md
```

For request -> backlog promotion, default to a split-first mindset:

- use `python logics/skills/logics.py flow assist suggest-split <request-ref> --format json` when the request spans multiple user flows, delivery surfaces, risks, or acceptance criteria;
- then use `python logics/skills/logics.py flow split request ...` to cover the request with several bounded backlog items;
- do not compress broad request coverage into only one or two oversized backlog items just to keep the split count low;
- use direct `promote request-to-backlog` only when the request is already atomic enough to map to one clear backlog slice.

The promotion flow seeds more of the next-stage document automatically:
- source indicators such as `From version`, `Understanding`, `Confidence`, `Complexity`, and `Theme`;
- request acceptance criteria into backlog acceptance criteria + AC traceability;
- backlog acceptance criteria into task AC traceability;
- source context/problem statements into the generated problem/context sections;
- actionable `Decision framing` follow-up text inside the generated doc itself.
- generated docs are prevalidated during generation/promotion so stale Mermaid signatures and incomplete AC traceability are caught before audit time.

Split a broad request/backlog item into several executable children:

```bash
python logics/skills/logics.py flow split request logics/request/req_001_example.md --title "Slice A" --title "Slice B"
python logics/skills/logics.py flow split backlog logics/backlog/item_002_example.md --title "Task A" --title "Task B"
```

`logics.yaml` now drives the default split policy. The shipped default is `minimal-coherent`, so keep splits to the smallest coherent slice count unless you explicitly pass `--allow-extra-slices`.
In practice, request coverage still comes first: if a broad request needs several bounded backlog items, keep the slices explicit instead of collapsing them into one or two large items.

Close docs with automatic transition propagation:

```bash
python logics/skills/logics.py flow close task logics/tasks/task_003_example.md
python logics/skills/logics.py flow close backlog logics/backlog/item_002_example.md
python logics/skills/logics.py flow close request logics/request/req_001_example.md
```

When a task is actually finished, prefer the kit-native guarded flow instead of editing indicators manually:

```bash
python logics/skills/logics.py flow finish task logics/tasks/task_003_example.md
```

`finish task` closes the task, propagates closure to linked backlog/request docs when eligible, verifies that the linked chain stayed synchronized, appends finish/report evidence to the task, and leaves a completion note in linked backlog items. Use `close` only when you explicitly want the lower-level primitive.

Generated tasks now include explicit wave checkpoints:

- each completed wave should leave the repository in a coherent, commit-ready state;
- linked Logics docs should be updated during the wave that changes the behavior;
- prefer one reviewed commit checkpoint per meaningful wave rather than several undocumented partial states.
- if the shared AI runtime is active and healthy, use `python logics/skills/logics.py flow assist commit-all` for the commit checkpoint of each meaningful step, item, or wave.
- do not mark a wave or step complete until the relevant automated tests and quality checks have been run successfully.

When one orchestration task covers multiple backlog items:

- put one `- Derived from \`...\`` line per linked backlog item in the task `# Links` section;
- keep the lines explicit even when the task is a parent wave that spans several backlog slices;
- prefer the repo-relative backlog path so the generated task stays traceable without extra lookup.

Run workflow coherence audit:

```bash
python logics/skills/logics.py audit
python logics/skills/logics.py audit --stale-days 30
python logics/skills/logics.py audit --group-by-doc
python logics/skills/logics.py audit --format json
python logics/skills/logics.py audit --autofix-ac-traceability
python logics/skills/logics.py audit --refs req_001_example
python logics/skills/logics.py audit --paths logics/request logics/backlog
python logics/skills/logics.py audit --since-version 1.9.0
python logics/skills/logics.py flow sync refresh-mermaid-signatures
```

Use the guarded local dispatcher when you want a local model to propose a workflow action without giving it direct file-write authority:

```bash
python logics/skills/logics.py flow sync dispatch-context req_088_add_a_local_llm_dispatcher_for_deterministic_logics_flow_orchestration --include-graph --include-registry
python logics/skills/logics.py flow sync dispatch req_088_add_a_local_llm_dispatcher_for_deterministic_logics_flow_orchestration --model deepseek-coder-v2:16b --include-graph --include-registry
python logics/skills/logics.py flow sync dispatch req_088_add_a_local_llm_dispatcher_for_deterministic_logics_flow_orchestration --decision-file /tmp/dispatcher-decision.json --execution-mode execute
```

Dispatcher rules:

- `sync dispatch-context` builds a compact machine-readable bundle around `context-pack`, with optional graph, registry, and doctor summaries.
- `sync dispatch` validates a strict decision contract with only `new`, `promote`, `split`, `finish`, and safe non-destructive `sync` actions.
- `suggestion-only` is the default mode; use `--execution-mode execute` only when you explicitly want the runner to invoke the mapped Logics command.
- Dispatcher runs append JSONL audit records to `logics/dispatcher_audit.jsonl` unless you override `--audit-log`.
- The Ollama path is transport-specific only; the deterministic runner and decision schema stay runtime-agnostic.
- `sync build-index` refreshes the runtime cache used by repeated context, graph, doctor, validation, and registry operations.
- `sync show-config` exposes the effective `logics.yaml` merge so automation can inspect the active split policy, mutation mode, and cache path.
- `sync refresh-ai-context` and `sync migrate-schema` now support repo-configurable `transactional` apply-or-rollback semantics and emit JSONL audit records to `logics/mutation_audit.jsonl` by default.

Use the shared hybrid assist runtime when the user asks for repetitive delivery help that should opportunistically use Ollama but still degrade safely:

```bash
python logics/skills/logics.py flow assist runtime-status --format json
python logics/skills/logics.py flow assist roi-report --format json
python logics/skills/logics.py flow assist commit-all
python logics/skills/logics.py flow assist summarize-pr --format json
python logics/skills/logics.py flow assist summarize-validation --format json
python logics/skills/logics.py flow assist next-step req_089_add_a_hybrid_ollama_or_codex_local_orchestration_backend_for_repetitive_logics_delivery_tasks --format json
python logics/skills/logics.py flow assist triage req_090_add_high_roi_hybrid_ollama_or_codex_assist_flows_for_repetitive_logics_delivery_operations --format json
python logics/skills/logics.py flow assist handoff req_090_add_high_roi_hybrid_ollama_or_codex_assist_flows_for_repetitive_logics_delivery_operations --format json
```

Hybrid assist rules:

- prefer the named aliases over ad hoc shell commands;
- keep `python ...` as the canonical cross-platform launcher;
- `runtime-status` is the shared probe surface for plugin, Codex, and Claude integrations;
- `roi-report` is the shared observability surface for CLI automation and plugin insights, including explicit measured, derived, and estimated sections;
- use `--model-profile qwen-coder` when the operator explicitly wants the curated Qwen path instead of the default DeepSeek profile;
- the shared runtime keeps backend provenance, degraded reasons, audit JSONL, and measurement JSONL visible to downstream surfaces;
- risky execution stays bounded: `suggestion-only` remains the default unless the operator intent is explicit.

Manage legacy per-repository Codex overlays when several repos still need workspace-specific `CODEX_HOME` projections during migration or troubleshooting:

```bash
python logics/skills/logics-flow-manager/scripts/logics_codex_workspace.py register
python logics/skills/logics-flow-manager/scripts/logics_codex_workspace.py sync
python logics/skills/logics-flow-manager/scripts/logics_codex_workspace.py status
python logics/skills/logics-flow-manager/scripts/logics_codex_workspace.py doctor --fix
python logics/skills/logics-flow-manager/scripts/logics_codex_workspace.py run -- codex
python logics/skills/logics-flow-manager/scripts/logics_codex_workspace.py clean
```

This overlay manager is no longer the primary runtime path. The default model is a globally published kit under `~/.codex`, while this legacy flow keeps `logics/skills/` canonical in the repo, projects repo-local skills into `~/.codex-workspaces/<repo-id>/`, lets repo-local skills shadow same-named global skills, and keeps shared user assets such as `auth.json`, `config.toml`, and `skills/.system` referenced from the primary `~/.codex/` home when available.

After promotion:

- Ensure the backlog item has clear acceptance criteria + priority.
- Ensure the task has a step-by-step plan and at least 1–2 validation commands relevant to the work.
- Ensure broad requests are represented by several bounded backlog items rather than one or two oversized slices.
- Ensure each task explicitly treats successful test execution as a gate before closing any step or wave.
- Ensure each task uses the shared `flow assist commit-all` checkpoint when the AI runtime is active and healthy.
- Ensure the source request lists any generated backlog items in its Backlog section.
- Carry forward any linked `prod_###` and `adr_###` refs so downstream docs keep the product and architecture framing visible.

Before promotion:

- If `Understanding` or `Confidence` is below 90% in the source doc, run the **logics-confidence-booster** skill first to clarify and update indicators.
- If the need requires a non-trivial product framing document, write a product brief in `logics/product/` and reference it from the source doc before promotion.
- If the need requires a non-trivial technical decision, write an ADR in `logics/architecture/` and reference it from the source doc before promotion.
- For request docs, replace the default Mermaid scaffold with a diagram specific to the need before considering the request ready.
- For backlog/task docs, replace the default Mermaid scaffold with a doc-specific diagram whenever the default no longer reflects the real flow.
- Refresh the Mermaid block whenever the title, problem/need, acceptance criteria, plan, validation path, or source links change in a way that changes the delivery story.
- Before finalizing any Mermaid diagram, sanity-check that the labels still obey the Mermaid safety rules above so previewers do not fall back to raw source rendering.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/alexago83) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->