Define orchestration spec, repo capability profiles, task lanes, and artifact model

[nnoce14]

Summary

Define the control-plane contract for the Cellix orchestration system.

Why

The workflow should not be spread implicitly across ADRs, instructions, skills, agents, and hooks with no single governing source.

We need a machine-readable orchestration spec and a formal orchestration model that:

• selects the repo capability profile
• maps repo paths/packages into abstract classes
• enables the valid lane families for that repo
• determines which profile-specific behavior becomes available
• defines completion and escalation expectations
• defines artifact depth expectations
• defines workflow states and valid transitions
• stays intentionally small so consumer repos do not have to maintain a bloated manifest

Scope

Define a lightweight orchestration.spec.yaml

The spec should be convention-first and config-second.

The repo-local file should primarily express:

• version
• repo capability profile
• package/path class mappings
• optional overrides only when deviating from profile defaults

It should not require every repo to restate every lane, skill, hook, and agent when those can be inferred from profile defaults.

Define repo capability profiles

Define at least:

mixed-framework-and-app

Supports:

• reusable framework lane families
• application delivery lane family
• tooling/workflow lane
• docs/planning lane

framework-only

Supports:

• reusable framework lane families
• tooling/workflow lane
• docs/planning lane

application-only

Supports:

• application delivery lane family
• tooling/workflow lane
• docs/planning lane

Define abstract package/path classes

The orchestration system must reason about abstract classes rather than current namespace names.

Define at least:

• reusableFramework
• applicationPackages
• tooling
• docs

Define task lanes

Document the primary task lanes:

• reusable framework public-surface
• reusable framework internal
• application feature delivery
• tooling/workflow
• docs/architecture/planning

The repo capability profile determines which lane families are available.
Task classification determines which lane is selected for a specific run.

Define the workflow state model

Define the workflow as an explicit state machine with named states, valid transitions, and phase ownership rules.

At minimum, formalize:

• intake / initialized
• planning
• plan-complete
• implementing
• reviewing
• revising
• done
• blocked / escalated

The orchestration model must define:

• which transitions are valid
• which agent roles are valid in which states
• which states are lane-specific
• which transitions require evidence or approval

Authority model

Document the authority order for the orchestration system so behavior does not drift across layers:

1. orchestration spec
2. ADR / architecture policy intent
3. repo-wide and path-scoped instructions
4. skills
5. agent files
6. runtime summaries/artifacts

Hooks enforce and validate policy, but they do not invent policy.

Explicit integration with PR #186

Document how cellix-tdd participates:

• available only when the repo capability profile supports reusable framework work
• activated by framework-task routing rather than by global default
• not enabled in application-only repos

Artifact model

Define the default runtime artifact posture.

Default to minimal artifacts:

• intake.md
• plan.md
• final-summary.md

Allow richer per-phase artifacts only when required by:

• profile defaults
• task lane
• risk level
• parallel/multi-agent complexity

Future extensibility requirement

The spec design must explicitly support all of the following without redesigning the orchestration core:

• today’s mixed CellixJS repo
• a future framework-only Cellix repo
• future application-only consumer repos

Acceptance criteria

• orchestration.spec.yaml format defined
• spec is lightweight and convention-first
• repo capability profiles defined
• task lane model defined
• workflow state model and valid transitions defined
• abstract package/path classes defined
• authority model documented
• artifact model defined
• CellixJS mixed-profile example spec included
• framework-only example spec included
• application-only example spec included
• ADR-0025 created to formalize the orchestration model