init-project-orchestration

name	init-project-orchestration
description	Create or migrate project-level agents, repeatable project workflows, and planning state from one client-neutral contract, then render repository-scoped adapters for both Claude Code and Codex. Use when a research project needs role separation, project commands, formal phase tracking, or conversion from an existing Claude-only .claude/agents and .claude/commands setup.

Initialize project orchestration

Create the project source once under .ai/orchestration/. Treat Claude Code and Codex files as generated adapters, never as parallel authoring surfaces.

Resulting structure

.ai/orchestration/                 # canonical, client-neutral source
├── manifest.yaml
├── agents/<role>.md
└── commands/<workflow>.md

.claude/agents/project-<role>.md   # generated Claude agent
.claude/commands/project/<workflow>.md
.codex/agents/project-<role>.toml  # generated Codex agent
.agents/skills/project-<workflow>/SKILL.md
.planning/roadmap.md               # shared project state
.planning/state.md

Claude exposes a workflow as /project:<workflow>. Codex exposes the same workflow as $project-<workflow>. Both adapters derive from the same neutral command body. The namespace prevents collisions with global skills.

Phase 1: Assess

1. Resolve the project root from the argument or current directory. Confirm it is the intended research project before searching elsewhere.
2. Read the active client's project guidance. Read neutral project facts from AI.md, README.md, docs/, and .context/; do not treat the sibling client's guidance file as an additional instruction set.
3. Read .context/field-calibration.md, project memory, and .planning/ when present.
4. Classify the project:
   • experimental: data preparation and empirical estimation;
   • computational: software, algorithms, simulations, or experiments;
   • theoretical: formal models and proofs;
   • mixed: select roles and workflows from more than one preset.
5. Inventory existing neutral sources and generated adapters. Also inventory legacy non-generated .claude/agents/ and .claude/commands/ files.

Do not overwrite anything during assessment.

Phase 2: Confirm the design

Read the applicable preset under templates/presets/ and present:

• proposed project agents and their exact read/write boundaries;
• proposed project workflows and expected arguments;
• the initial .planning/ phases;
• any legacy single-client Claude files that need reconciliation.

Ask for one confirmation covering additions, removals, names, and project-specific standards. Agents implement; independent global agents review.

Phase 3: Author neutral sources

1. Create .ai/orchestration/manifest.yaml from templates/manifest-template.yaml. Keep namespace: project unless an existing checked-in namespace would collide.
2. Create one neutral agent source per confirmed role using templates/agent-template.md.
3. Create one neutral command source per confirmed workflow using templates/command-template.md.
4. Always include commands/update-state.md, starting from templates/update-state-command.md.
5. Populate real project paths, standards, and ownership boundaries. Do not leave placeholders.

Canonical sources must not contain client-home paths, machine-absolute paths, Claude/Codex adapter directories, or client-specific invocation syntax. Refer to reusable global capabilities as “the latex skill”, for example.

Agent policy

• Use artifact_contract.mode: response-only plus write_policy.project: read-only for an advisory agent.
• Use artifact_contract.mode: project-write plus write_policy.project: scoped-write for an implementation agent.
• Keep write_policy.git: forbidden unless the user explicitly authorizes Git mutation as part of that role.
• Declare behavioral capabilities and the minimum Claude adapter tools. Codex derives a read-only or workspace-write sandbox from the neutral write policy.
• Treat every data/raw/ path as read-only.

Phase 4: Reconcile an existing Claude project

If legacy project agents or commands exist:

1. Read every non-generated legacy file.
2. Convert its substantive behavior into the matching neutral source.
3. Replace client-bound guidance-file reads with “active client guidance” plus the relevant neutral project files.
4. Convert slash-skill calls to semantic skill references.
5. Preserve tool and write restrictions in neutral policy fields.
6. Compare the neutral source against the legacy file before rendering.

The renderer refuses to overwrite a non-generated target. Keep unmatched legacy files in place and report them; never select one side silently.

Phase 5: Render and verify

Resolve scripts/project-orchestration.py relative to this skill directory, then run it through uv:

uv run <skill-root>/scripts/project-orchestration.py render --project <project-root>
uv run <skill-root>/scripts/project-orchestration.py check --project <project-root>

The renderer:

• validates the neutral schemas and portability constraints;
• writes both clients' adapters atomically;
• refuses symlinked parents and non-generated collisions;
• removes only stale files carrying its own generated marker;
• exits non-zero when check detects drift.

Never edit a generated adapter. Change .ai/orchestration/ and render again.

Phase 6: Planning and guidance pointers

Create .planning/roadmap.md and .planning/state.md from the bundled templates only when they are absent. When they exist, merge deliberately and preserve current decisions and progress.

Add a short pointer to each existing client guidance file without duplicating the orchestration body:

• canonical project roles/workflows: .ai/orchestration/;
• shared phase state: .planning/roadmap.md and .planning/state.md;
• generated adapters for that client;
• rerender command.

Do not create or overwrite a large CLAUDE.md or AGENTS.md merely to install orchestration. Shared project facts belong in neutral project documentation.

Completion report

Report:

• neutral agent and workflow sources created or migrated;
• generated Claude and Codex adapter counts;
• planning files created, merged, or preserved;
• any legacy file still awaiting reconciliation;
• the exact renderer check result.

Do not commit or push unless the user separately requests it.