Skip to content

projio: model project code tiers in config (core_library + project_utils)

Context

Projects have a three-tier code architecture that projio should model explicitly:

  1. core_library (e.g., cogpy at code/lib/cogpy/) — dataset-agnostic atomic compute functions. Reusable across projects. This is where nb_promote should send library-worthy logic.
  2. project_utils (e.g., code/utils/) — project-specific glue. Pipeline-architecture-aware helpers that don't fit into the core library (epoch helpers, matlab interop, notebook bootstrap). NOT pipeline wiring (that's pipeio's job now).
  3. flow scripts (code/pipelines/{flow}/scripts/) — snakemake wiring, one script per rule. Imports from tiers 1 and 2.

Currently: - pipeio scaffolding (nb_create, script_create, mod_create) queries codio for kind=internal libraries but codio's catalog is empty - codio's kind vocabulary doesn't distinguish between "I develop this" (cogpy) and "it's installed from elsewhere" (labbox) - code/utils/ isn't tracked anywhere — it's not in code/lib/, not in codio, not in projio config - The old utility-promote pixecog skill encoded placement heuristics in prose; those should be machine-queryable

Proposed config addition

# .projio/config.yml
code:
  core_library: cogpy          # code/lib/{name} — atomic compute, nb_promote target
  project_utils: code/utils    # project glue — PipelineContext, helpers
  lib_dir: code/lib            # where all libraries live (for auto-discovery)

Implementation

  1. projio config model: Add code section to config schema. Parse in _load_config().

  2. projio init / sync: Auto-discover code/lib/*/ directories and register in codio catalog:

  3. core_library value → kind: project_library (or relationship: develop)
  4. Other code/lib/*/ → kind: shared (installed, not developed here)

  5. Register project_utils path if it exists

  6. pipeio scaffolding: Query projio config (or codio) for:

  7. nb_create → import core_library + project_utils in bootstrap
  8. script_create → import core_library for compute functions

  9. nb_promote → route extracted code: library-worthy → core_library, project glue → project_utils, flow-specific → scripts/

  10. codio vocabulary: Either extend kind enum (project_library, shared_library, external) or add a relationship field. The key question for agents: "can I add code to this library?"

What this replaces

The pixecog utility-promote skill's placement heuristics become machine-queryable: - "Is this dataset-agnostic?" → core_library (cogpy) - "Does it use PipelineContext/registry/snakemake?" → project_utils (code/utils) - "Is it specific to one rule?" → flow script

Note on pixecog's code/utils

Much of utils.io (PipelineRegistry, PipelineContext, Session, Stage) has been superseded by pipeio. The remaining valuable parts are project-specific: notebook_bootstrap, brainstate epoch helpers, matlab interop. A cleanup pass should deprecate the pipeio-superseded parts.

  • [[docs/log/issue/issue-arash-20260327-155921-977015.md]] — Directly related: codio bugs and unclear MCP docs — the current note proposes extending codio's kind vocabulary to distinguish internal vs external libraries
  • [[docs/log/issue/issue-arash-20260326-232732-019412.md]] — Pipeio implementation issue — the current note mentions pipeio scaffolding tools (nb_create, script_create, mod_create) querying codio for kind=internal libraries
  • [[docs/log/issue/issue-arash-20260331-172245-820267.md]] — MCP tools reference docs are undocumented — adding code tier config would require documenting new config schema and affected tools