Skip to content

cogni-dao/cogni / .claude/skills/conductor-worktree-setup

conductor-worktree-setup

Verified

Use when setting up, reviewing, or changing Cogni Conductor worktree bootstrap, including .conductor/settings.toml, scripts/conductor-worktree-setup.sh, secret/auth symlinks, and AI launch-pack references for human or AI developers.

FileKindSize
SKILL.mdskill md3.1 KB
---
name: conductor-worktree-setup
description: Use when setting up, reviewing, or changing Cogni Conductor worktree bootstrap, including .conductor/settings.toml, scripts/conductor-worktree-setup.sh, secret/auth symlinks, and AI launch-pack references for human or AI developers.
---

# Cogni Conductor Worktree Setup

Use this with the bundled Conductor app skill when a human asks how to run Cogni in Conductor or when changing the repo's worktree bootstrap.

## Ground Truth

- `.conductor/settings.toml` wires Conductor setup to `bash scripts/conductor-worktree-setup.sh`.
- `scripts/conductor-worktree-setup.sh` is the canonical setup script.
- `https://cognidao.org/knowledge/operator-worktree-setup` is the human-facing worktree guide.
- `.claude/skills/node-wizard-expert/SKILL.md` and `nodes/operator/app/src/features/nodes/launch-pack.ts` are the launch-handoff references.

## Human Flow

1. Set `COGNI_TEMPLATE_ROOT` to the primary checkout if it is not `$HOME/dev/cogni-template`.
2. In the primary checkout, update `main` before creating the Conductor workspace:
   ```bash
   git -C "$COGNI_TEMPLATE_ROOT" checkout main
   git -C "$COGNI_TEMPLATE_ROOT" pull --ff-only origin main
   ```
3. Create the Conductor workspace from that fresh base.
4. Let Conductor run the committed setup script. Local setup reconciles the
   stable user-level Codex cognition hook before installing dependencies.
5. In Codex, open `/hooks` once and trust that user-level SessionStart hook.
   Later local worktrees reuse the same trusted hook path.

The setup script also fetches `origin/main`, merges it into the new workspace branch (it warns and leaves the branch as-is on a dirty tree, detached HEAD, or conflict), and fast-forwards the primary checkout only when it is already on clean `main`. It warms the session cognition cache right after linking `.env.cogni`; every agent session still fetches its own bundle at start.

## Invariants

- Ensure the primary checkout has `COGNI_NODE_API_KEY`, then symlink `.env.cogni` and `.local-auth` from the primary checkout; never copy them into worktrees. `COGNI_NODE_API_KEY` is the loader's lookup name, not a separate identity: it may intentionally alias the same bearer as `COGNI_API_KEY_PROD`/`COGNI_API_KEY`. Authentication and action-specific RBAC must be proven separately; never re-register merely to populate another variable name.
- Keep the fleet-standard `pnpm install --offline --frozen-lockfile || pnpm install --frozen-lockfile`, `pnpm packages:build`, and `pnpm worktree:check` in the setup path. The first attempt is cache-only; the fallback fetches newly pinned tarballs and also retries transient filesystem failures once.
- Local setup (`CONDUCTOR_IS_LOCAL=1`, including the local default) must reconcile the stable user-level Codex cognition hook. Cloud setup must not modify a user-level Codex home.
- Codex still requires one explicit `/hooks` trust for that stable user-level hook; automatic reconciliation does not bypass trust.
- If the setup contract changes, update the script, this skill, `https://cognidao.org/knowledge/operator-worktree-setup`, and launch-pack wording together.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall