plumbline-init

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Initialize Plumbline

This skill is explicit only. It is the consent boundary for repository-local routing and the project-local agent team. Treat initialization as one guarded setup transaction, not as background bootstrap.

## Guard and assessment

Before inspecting files, check whether this conversation already contains unrelated active implementation work. If it does, recommend a fresh task and stop unless the user explicitly says `continue here`.

Start read-only and keep discovery targeted. Begin with repository guidance, README files, manifests, validation scripts, and only the config and paths that determine Plumbline integration. Do not dump a broad recursive file listing or start dependency installation.

Inspect enough to understand:

- `AGENTS.md`, `CLAUDE.md`, README files, documentation routing, and canonical document ownership;
- build, validation, UAT, Git, and managed-worktree conventions;
- Codex `.codex/config.toml` and `.codex/agents/` when Codex is the host;
- Claude `.claude/agents/` and relevant project `.claude/settings.json` entries when Claude Code is the host;
- `.gitignore`, `.git/info/exclude`, and `.worktreeinclude`;
- `git worktree list --porcelain` and whether the target is a normal checkout or worktree;
- installed local skills, workflow plugins, and competing automatic controllers.

For Codex, read the global `config.toml` only to report host capability and the current model/reasoning candidate. It is not an agent source or fallback. For Claude Code, inspect project-local capability only; never read or modify global Claude settings as part of initialization. Never read, select, copy, or inherit personal/global custom-agent files. Treat an installed workflow plugin as available, not active, unless the user explicitly selected it or repository-local runtime evidence shows it owns the task. Do not modify global settings or disable another plugin during initialization.

Adopt an established repository's terminology and document structure. Do not create a parallel docs taxonomy just because Plumbline is new. For a new project, ask only for a concise product baseline: purpose, users, important behavior, priority, constraints, and non-goals.

## Required proposal

For router-only setup or repair, keep any existing team unchanged and skip
role/model discovery and the team proposal table. Preview only the router
installer's activation, ignore, and selected propagation changes.

Present one reviewable proposal and wait for explicit approval before writing anything. Show the proposed agent set in a table with one row per role and these columns:

`role | why it is needed | host-native model value | reasoning/effort | sandbox/permission intent | write access`

Use the current project/main model when available; otherwise show a host model only as a candidate to approve. Do not invent a model slug or alias. Treat the table as a recommended, role-aware starting profile aimed at the cheapest effective model and reasoning/effort: lower-cost settings for bounded research or mechanical work, higher settings only for material architecture, persistence, concurrency, security, ownership, or acceptance risk. These values are adjustable and hotswappable after setup.

For a team proposal, read and apply `references/model-selection.md` in full.
Recommend the latest supported Sol/Luna families for Codex and Opus/Sonnet for
Claude, then resolve current supported model IDs and efforts for this installation.
The reference owns the role-aware starting recommendations and discovery rules;
they are adjustable, not a required team or immutable policy.

The `maintainable-code` skill is model-invoked for implementation and review;
`code-reviewer` runs before `qa-auditor` on material code.

On explicit repeat initialization, repeat discovery and compare existing approved
IDs for availability and deprecation. Keep them unless a replacement is approved;
the adapters write explicit values supplied by the proposal and have no dated
model fallback. Discovery failure leaves existing profiles unchanged and new
unresolved pins unapplied. Claude's `opus`, `sonnet`, `haiku`, and `fable` aliases
are discovery inputs, not the exact IDs to write for a versioned model pin.

For Codex, explain that current releases enable subagents by default. Recommend `agents.enabled = true` only as an explicit project intent and `agents.max_concurrent_threads_per_session = 12` as an adjustable, user-owned starting value; preserve an existing or approved alternative such as 6. Detect legacy `features.multi_agent`, `agents.max_threads`, and `agents.max_depth` entries and offer their exact migration for approval. A selected role's explicit `model` field is sufficient to select the approved current model, including a full leaf-model ID, through current v2 delegation; do not force a v1 path or claim that a depth setting is required. For Claude Code, recommend project `.claude/agents/*.md` definitions with the role-aware `model`/`effort` baseline above, restricted tools and `permissionMode: plan` for report-only roles, and no `Agent` tool for any generated role. Claude automatically matches descriptions; the main thread can explicitly name a role in its dispatch prompt or use `@agent-<role>` for one task. Do not use `--agent` to dispatch a worker, enable Claude's experimental Agent Teams, or edit global settings.

The same proposal must name every selected change and state `Create`, `Keep`, `Patch`, or `Skip`:

- install `.agents/skills/plumbline-router/SKILL.md` from `templates/router/SKILL.md`, its conditional managed `AGENTS.md` activation block, and the router's local ignore rule, even when no team is selected; for Claude also import `@AGENTS.md` in `CLAUDE.md`;
- create or audit the selected project agents using the host adapter: `.codex/agents/*.toml` for Codex or `.claude/agents/*.md` for Claude Code;
- for Codex, create or patch project `.codex/config.toml` with current `agents.enabled` and concurrency settings only when approved;
- add or update the host guidance section in `AGENTS.md` with delegation and no-child rules; for Claude Code, add the supported `@AGENTS.md` import to `CLAUDE.md`; on a later explicit `$plumbline-init`, audit both and offer a guidance-only refresh when either is stale;
- add local `.git/info/exclude` entries so the host agent files and router stay untracked;
- recommend router propagation for local Codex-managed worktrees independently of team setup; when approved, patch root `.gitignore` and `.worktreeinclude` for the selected ignored paths and show both changes together. The router stays untracked. Remote/manual worktrees and new clones need explicit local setup; do not promise that `.worktreeinclude` covers them;
- repair documentation routing only if the repository already needs it;
- identify competing controllers and offer reversible conflict actions without applying them.

Before asking for approval, run the host-specific candidate installer with `--dry-run --format json` and include the file/operation/field manifest in the proposal: `scripts/install_agent_team.py` for Codex or `scripts/install_claude_agent_team.py` for Claude Code. For an existing setup, use the same preview for `--mode initialize --update-agents --refresh-agents`; it changes only the managed `AGENTS.md` section for Codex or the managed Claude guidance plus its `CLAUDE.md` import for Claude Code. If the section is an older unmarked block, the preview must report that `--replace-agents-guidance` is required. If a repository-local router already exists, the preview must state whether it matches the current template and whether `--replace` would be required; never overwrite it merely because it is stale. This is read-only and does not approve or apply anything.

For router-only setup, run `scripts/install_router.py --root <checkout> --dry-run
--format json`, adding `--propagate` for the approved local worktree scope and
`--host claude` on Claude Code. Its manifest includes the conditional activation
block and ignore rules. Run the same preview when upgrading an existing router;
apply a differing copy only with the approved `--replace`. Reuse current role
profiles; router repair requires no team creation or retuning.

## After approval

Apply only the approved items. Rerun the dry-run manifest; if the target changed, refresh the proposal before writing. Then rerun the host-specific installer without `--dry-run` using the approved roles, exact host-native model, reasoning/effort, thread cap where applicable, and explicit `--update-agents`/`--propagate` choices. On a later explicit initialization, repeat model lookup and compare the project profiles with the current host values; use the adapter's `--mode retune --update-profile` path for an approved profile change so only `model` plus reasoning/effort changes. This does not replace role instructions, permissions, sandbox/permission intent, or custom fields. Use `--update-agents --refresh-agents` for a guidance-only refresh; this does not replace roles or change config, and for Claude Code it also repairs the `CLAUDE.md` import without duplicating the guidance block. Apply `--replace-agents-guidance` only after the user approves the exact preview of an older unmarked section, and replace only the managed section while preserving the rest of `AGENTS.md` and `CLAUDE.md`. Use the same dry-run/apply sequence with `scripts/install_router.py` for the approved router. For existing teams, run `--mode audit` first; it is read-only and does not need `--replace`. A normal `--mode retune` preserves existing model, reasoning/effort, sandbox/permission, custom fields, and instructions; use `--fill-missing`, `--update-profile`, or the explicitly approved `--update-instructions` flag for narrow changes. `--replace` is reserved for an explicitly approved initialize replacement. Never write global or personal agent files.

Validate Plumbline setup separately from repository product checks. Report Plumbline files/config/TOML-or-Markdown/ignore/worktree validation as passed or failed; preflight repository commands for missing dependencies or executables; and label repository checks as passed, skipped, or blocked. Missing dependencies are a repository bootstrap blocker, not a Plumbline setup failure, and do not justify starting `npm ci` or another install without approval. Validate required host fields, Codex collaboration state and any user-owned concurrency value, AGENTS guidance, local discovery paths, ignore rules, exact changed-field output, `git diff --check`, and the `.worktreeinclude` contents. Explain that propagation affects new managed worktrees only when the host/repository workflow supports it; the `.worktreeinclude` manifest must be committed for future worktrees to see it, and existing worktrees need explicit refresh or local copy. A delegation wave must report selected role names with host-native model and reasoning/effort values in one compact line; otherwise report `Direct: <reason>` and continue on the main thread. End initialization and recommend a fresh task for feature work.

A writable parent is normal during a goal. For researcher, architect, code-reviewer, and QA dispatches, require a report-only brief with no write set. Implementers and code-reviewers use the bundled `maintainable-code` skill for their respective implementation and adversarial review work. Codex `sandbox_mode = "read-only"` and Claude `permissionMode: plan` are intent rather than proof of hard isolation when a parent is writable or permissive. If the host cannot provide hard read-only isolation when it is required, use `Direct: delegation prohibited or effective read-only isolation unavailable`.

## Completion

The read-only proposal is complete when it names the host, selected roles,
model/reasoning or effort values, permission intent, config changes, file
manifest, propagation effects, and validation expectations. Approved setup is
complete when only the approved files changed, exact changed fields are
reported, Plumbline validation is separated from repository bootstrap checks,
and the resulting local discovery and worktree-propagation state is verified.
Recommend a fresh task for feature work after setup.

From nickyfactz/plumbline, MIT.

More from nickyfactz/plumbline