convertible-cli 0.1.2__tar.gz

convertible_cli-0.1.2/.claude/skills/agent-config/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: agent-config
+description: >
+  Show a Culture agent's full configuration in one read-only view: its
+  system-prompt file (CLAUDE.md / AGENTS.md / GEMINI.md), the parallel
+  culture.yaml, and the agent's local .claude/skills index. Use when an
+  operator says "show agent <name>", "what does <agent> look like", or before
+  teaching/onboarding an agent and you need to see its current kit + config.
+  Backs the `guild show` verb. Vendored from steward (cite-don't-import);
+  inventory only — it reports, it does not judge alignment or drift.
+type: command
+---
+
+# agent-config — surface a Culture agent's config in one view
+
+guildmaster is the mesh's skills supplier and owns the **inventory** surfaces:
+"what kit + config does this agent have?" This skill answers exactly that for a
+single agent, showing the three artifacts that together define it:
+
+1. **System-prompt file** (`CLAUDE.md` / `AGENTS.md` / `GEMINI.md`) — the
+   prompt-side guidance for the agent's backend. The script detects which file
+   is present from a backend-fingerprint registry.
+2. **`culture.yaml`** — the runtime-side config (`agents:` list with `suffix`,
+   `backend`, `model`, `system_prompt`, `channels`, `tags`, `acp_command`,
+   `extras`). Lives parallel to the prompt file at the project root.
+3. **`.claude/skills/*/SKILL.md`** — the per-project skills the agent can
+   invoke, one line each (name + truncated description).
+
+This is the **inventory half** of the steward → guildmaster split
+([issue #12](https://github.com/agentculture/guildmaster/issues/12)): it reports
+the config, it does **not** interpret drift or judge alignment. The relationship
+graph and the "is this agent aligned?" judgment stay with `steward overview` /
+`steward doctor`.
+
+## When to use
+
+- Before `guild teach` / `guild onboard` — see an agent's current kit + config.
+- When an operator asks "show me agent `<name>`" or "what does `<agent>` run".
+- Read it, don't guess — before answering a question about what an agent does.
+
+## How to run
+
+One script, two ways to call it (or just run `guild show`, which wraps it):
+
+```bash
+# Path mode — point at any directory with a prompt file + culture.yaml
+.claude/skills/agent-config/scripts/show.sh ../culture
+
+# Suffix mode — resolve a registered agent suffix via the Culture server's
+# manifest (location set by culture_server_yaml in skills.local.yaml)
+.claude/skills/agent-config/scripts/show.sh daria
+```
+
+Output is three sections: the detected system-prompt file, `culture.yaml` (or
+`(missing)`), and a one-line summary per local skill (name + description,
+truncated to 120 chars).
+
+## What to look at in `culture.yaml`
+
+| Field | Why it matters |
+|-------|----------------|
+| `suffix` | Identifies the agent on the mesh. |
+| `backend` | One of `claude` / `codex` / `copilot` / `acp`. The all-backends rule means a feature in one must land in all four. |
+| `model` | Drift here changes behavior silently. |
+| `system_prompt` | Should not contradict the prompt file. |
+| `channels` | Where the agent listens. |
+| `tags`, `extras`, `acp_command` | Backend-specific. |
+
+## Notes
+
+- **Read-only.** The script never edits agent files. It reports; it does not
+  flag or fix drift — that judgment is steward's lane.
+- **Backend-aware.** Prompt-file detection comes from
+  `data/backend-fingerprints.yaml` (the `prompt:` mapping), falling back to the
+  built-in `(CLAUDE.md AGENTS.md GEMINI.md)` list if the registry is absent.
+- **Per-machine config.** Suffix mode reads `culture_server_yaml` from
+  `.claude/skills.local.yaml` (git-ignored), falling back to
+  `.claude/skills.local.yaml.example`.
+- **Vendored from steward** (`agent-config`). guildmaster owns this copy and may
+  diverge; re-sync from steward's canonical copy when it changes. Divergences:
+  the SKILL.md is reframed for guildmaster's inventory role and adds
+  `type: command` for the culture backend's skill loader.

convertible_cli-0.1.2/.claude/skills/agent-config/data/backend-fingerprints.yaml

@@ -0,0 +1,30 @@
+# Canonical backend fingerprint registry. Vendored from steward's agent-config
+# skill (cite-don't-import); guildmaster owns this copy. Read by the agent-config
+# show.sh (bash), which `guild show` shells out to. Upstream steward also reads
+# it from a Python detector; guildmaster has no parallel detector, so only the
+# `backends:` prompt mapping below is load-bearing here. Keep that mapping in
+# sync with upstream when re-syncing.
+#
+# `prompt`        — the backend's system-prompt filename at the repo root.
+# `steering`      — files/dirs distinctive enough to attribute to this backend.
+# `shared_steering` — files/dirs that belong to NO specific backend. A repo
+#                   declared as any backend may have these without triggering a
+#                   mismatch. `.agents` is a generic Culture agent-config
+#                   convention. `.claude/settings.json` and
+#                   `.claude/settings.local.json` are generic Claude Code
+#                   (editor/CLI) workspace config files — they appear in any
+#                   repo that uses Claude Code as the development tool,
+#                   regardless of the agent backend, so they must never be used
+#                   to infer the backend or flag a mismatch. The claude backend
+#                   is identified solely by its `CLAUDE.md` prompt file.
+#                   `.github/copilot-instructions.md` is generic GitHub Copilot
+#                   editor/IDE config — any repo may have it regardless of the
+#                   declared agent backend, so it must not trigger a mismatch.
+backends:
+  claude:  { prompt: CLAUDE.md, steering: [] }
+  codex:   { prompt: AGENTS.md, steering: [".codex"] }
+  acp:     { prompt: AGENTS.md, steering: [".kiro"] }
+  copilot: { prompt: AGENTS.md, steering: [] }
+  gemini:  { prompt: GEMINI.md, steering: [".gemini"] }
+shared_steering: [".agents", ".claude/settings.json", ".claude/settings.local.json", ".github/copilot-instructions.md"]
+prompt_fallback: AGENTS.md

convertible_cli-0.1.2/.claude/skills/agent-config/scripts/show.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# Show a Culture agent's full configuration in one view:
+# the detected system-prompt file (CLAUDE.md / AGENTS.md / GEMINI.md), the
+# parallel culture.yaml, and the .claude/skills/ index.
+#
+# Usage: show.sh <path-or-agent-suffix>
+#
+# Path mode:   show.sh ../culture
+# Suffix mode: show.sh daria   (resolved via culture_server_yaml in skills.local.yaml)
+#
+# Exit codes:
+#   0   success
+#   1   environment error (missing manifest, missing PyYAML for suffix mode)
+#   2   user error (no target given, unknown suffix, target path doesn't exist)
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+REPO_ROOT="$(cd "$SKILL_DIR/../../.." && pwd)"
+
+CFG="$REPO_ROOT/.claude/skills.local.yaml"
+[ -f "$CFG" ] || CFG="$REPO_ROOT/.claude/skills.local.yaml.example"
+
+# Read a top-level YAML scalar from CFG. Schema is intentionally tiny:
+#   key: value     (with optional surrounding quotes / trailing comment)
+# No PyYAML dependency.
+read_cfg() {
+    awk -v key="$1" '
+        $0 ~ ("^" key ":[[:space:]]*") {
+            sub("^" key ":[[:space:]]*", "")
+            sub(/[[:space:]]*#.*$/, "")
+            sub(/^[[:space:]]+/, ""); sub(/[[:space:]]+$/, "")
+            sub(/^["\047]/, ""); sub(/["\047]$/, "")
+            print
+            exit
+        }
+    ' "$CFG"
+}
+
+target="${1:-}"
+if [ -z "$target" ]; then
+    echo "Usage: $(basename "$0") <path-or-agent-suffix>" >&2
+    exit 2
+fi
+
+if [ -d "$target" ]; then
+    DIR="$target"
+else
+    SERVER_YAML_RAW="$(read_cfg culture_server_yaml)"
+    SERVER_YAML="${SERVER_YAML_RAW/#\~/$HOME}"
+    if [ ! -f "$SERVER_YAML" ]; then
+        echo "no server manifest at $SERVER_YAML — set culture_server_yaml in $CFG" >&2
+        echo "or pass an explicit path instead of suffix '$target'" >&2
+        exit 1
+    fi
+    # Suffix mode parses Culture's server manifest, whose schema is dictated by
+    # Culture (not by us) and includes nested mappings — too rich for awk.
+    # We use python+PyYAML here, with a friendly install hint if it's missing.
+    if ! python3 -c 'import yaml' 2>/dev/null; then
+        echo "suffix mode needs Python + PyYAML to parse $SERVER_YAML" >&2
+        echo "  install: pip install --user pyyaml   (or: uv pip install pyyaml)" >&2
+        echo "  or pass an explicit path instead of suffix '$target'" >&2
+        exit 1
+    fi
+    # Use a dedicated exit code (2) for "unknown suffix" so the steward CLI
+    # wrapper can distinguish user errors (typo'd suffix) from env errors
+    # (missing manifest / PyYAML).
+    if ! DIR=$(python3 - "$SERVER_YAML" "$target" <<'PY'
+import sys, yaml, pathlib
+manifest_path, suffix = sys.argv[1], sys.argv[2]
+m = yaml.safe_load(pathlib.Path(manifest_path).read_text()) or {}
+agents = m.get('agents', {})
+entry = agents.get(suffix)
+if entry is None:
+    print(f"no agent registered with suffix {suffix!r} in {manifest_path}", file=sys.stderr)
+    sys.exit(2)
+print(entry['directory'] if isinstance(entry, dict) else entry)
+PY
+); then
+        exit 2
+    fi
+fi
+
+DIR="${DIR/#\~/$HOME}"
+
+# Recognized prompt filenames come from the shared registry (single source
+# of truth with the Python detector). Fall back to the built-in list if the
+# registry isn't present (e.g. skill vendored without the data file).
+REGISTRY="$SKILL_DIR/data/backend-fingerprints.yaml"
+prompt_files=()
+if [ -f "$REGISTRY" ]; then
+    while IFS= read -r pf; do
+        [ -n "$pf" ] && prompt_files+=("$pf")
+    done < <(grep -oE 'prompt:[[:space:]]*[^,}[:space:]]+' "$REGISTRY" | awk '{print $NF}' | sort -u)
+fi
+[ ${#prompt_files[@]} -eq 0 ] && prompt_files=(CLAUDE.md AGENTS.md GEMINI.md)
+
+shown=0
+for pf in "${prompt_files[@]}"; do
+    if [ -f "$DIR/$pf" ]; then
+        echo "=== $DIR/$pf ==="
+        cat "$DIR/$pf"
+        echo
+        shown=1
+    fi
+done
+if [ "$shown" -eq 0 ]; then
+    echo "=== $DIR (system prompt) ==="
+    echo "(no recognized prompt file: ${prompt_files[*]})"
+    echo
+fi
+echo "=== $DIR/culture.yaml ==="
+if [ -f "$DIR/culture.yaml" ]; then cat "$DIR/culture.yaml"; else echo "(missing)"; fi
+echo
+echo "=== $DIR/.claude/skills/ ==="
+found=0
+for s in "$DIR"/.claude/skills/*/SKILL.md; do
+    [ -f "$s" ] || continue
+    found=1
+    name=$(awk '/^name:/{print $2; exit}' "$s")
+    desc=$(awk '
+        /^description:/ {
+            sub(/^description:[[:space:]]*/, "")
+            buf = $0
+            flag = 1
+            next
+        }
+        flag && /^[a-z_-]+:/ { flag = 0 }
+        flag { buf = buf " " $0 }
+        END { gsub(/^[[:space:]]+|[[:space:]]+$/, "", buf); print buf }
+    ' "$s")
+    printf "  %-30s %s\n" "$name" "${desc:0:120}"
+done
+if [ "$found" -eq 0 ]; then
+    echo "  (no skills)"
+fi

convertible_cli-0.1.2/.claude/skills/assign-to-workforce/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: assign-to-workforce
+type: command
+description: >
+  Fan out a converged devague plan's dependency waves to parallel agents in
+  isolated git worktrees, one agent per task per wave, with TDD-gated merges
+  by the main agent. Human gates: the exported spec, the implementation split
+  plan (task map + per-task agent/model proposal + go/no-go), and the final PR.
+  The devague CLI stays deterministic and non-orchestrating (#20) — it only
+  *describes* the graph via `devague plan waves`; the operator (main agent)
+  performs the fan-out. Use when the user says "assign to workforce",
+  "fan out the plan", "parallel subagents", or after /spec-to-plan exports a
+  plan. Authored and maintained in agentculture/devague (origin = devague);
+  steward pulls this skill from here and broadcasts it to the AgentCulture
+  mesh — it is NOT vendored from steward like the other skills here.
+---
+
+# assign-to-workforce — fan out a converged plan's waves to parallel agents
+
+The skill is named **`assign-to-workforce`**; the product/CLI it reads is the
+**`devague plan waves`** command. (The prior leg — turning a spec into a plan —
+is the sibling **`/spec-to-plan`** skill.)
+
+`assign-to-workforce` takes a **converged devague plan** and fans out its
+dependency waves to parallel agents (subagents, teammate agents, or generalist
+agents) — one agent per task per wave — each working in an **isolated git
+worktree**. The main agent merges each completed worktree gated by TDD. The
+human owns exactly three gates: the exported spec, the implementation split
+plan, and the final PR.
+
+The devague CLI is **never orchestrated by devague itself** — `devague plan
+waves` describes the dependency graph (#20); it does not spawn agents, manage
+worktrees, mark tasks done, or pick a backend. The fan-out is the *operator's*
+job — this skill and the main agent perform it.
+
+## How to run
+
+The entry point is `scripts/assign-to-workforce.sh`. Invoke it from the
+repository whose plan you are implementing (plans persist under `.devague/`
+in the current directory):
+
+```bash
+bash .claude/skills/assign-to-workforce/scripts/assign-to-workforce.sh split-plan [--plan <slug>]
+bash .claude/skills/assign-to-workforce/scripts/assign-to-workforce.sh waves    [--plan <slug>] [--json]
+bash .claude/skills/assign-to-workforce/scripts/assign-to-workforce.sh help
+```
+
+It resolves the CLI portably — an installed `devague` on `PATH` (the normal
+case), falling back to `uv run devague` when you are inside the devague
+checkout, else an install hint. The `split-plan` subcommand reads
+`devague plan waves --json` and renders the human-facing implementation split
+plan: task map, proposed per-task agent + model assignment, and the go/no-go
+question. The `waves` subcommand forwards to `devague plan waves` verbatim.
+
+### Usage
+
+| Subcommand | What it does |
+|------------|--------------|
+| `split-plan [--plan S]` | Read `devague plan waves` and print the implementation split plan — task map with per-task agent + model proposal — ready for human go/no-go review. |
+| `waves [--plan S] [--json]` | Forward to `devague plan waves [--json]`. Read-only; lists wave batches. On a converged plan exits 0 listing the waves. |
+| `help` | Print usage. |
+
+## The full flow
+
+The flow has three human gates and one automated TDD merge loop.
+
+### Human gate 1 — the exported spec
+
+The plan is seeded from a converged frame (`devague plan new --frame <slug>`).
+The human reviewed and approved the spec when it was exported by the `/think`
+skill. No re-approval needed here — the spec gate is already closed.
+
+### Human gate 2 — the implementation split plan
+
+Before any task is assigned, the main agent presents the **implementation split
+plan** for human go/no-go. This is the only gate the human owns at the
+implementation stage (per task, the TDD gate is the main agent's).
+
+The split plan contains:
+
+1. **Task map** — every task id, its one-line summary, acceptance criteria, and
+   the wave it belongs to (from `devague plan waves`).
+2. **Per-task agent + model proposal** — for each task: the proposed agent type
+   (subagent / teammate / generalist), the proposed model (e.g. a cheaper/faster
+   model for a well-scoped task), and the scope justification (why this task is
+   safe to delegate).
+3. **Go/no-go question** — explicit human decision: "Approve this split and
+   assign the plan to the workforce, or edit it first?"
+
+The human may edit any row (agent type, model, scope) before approving. The
+plan is model-agnostic — devague does not pick a backend (#20).
+
+Run `split-plan` to print the proposed table:
+
+```bash
+bash .claude/skills/assign-to-workforce/scripts/assign-to-workforce.sh split-plan
+```
+
+Do not proceed to fan-out until the human approves the split plan.
+
+### Fan-out — one agent per task per wave in isolated worktrees
+
+Once the human approves, the main agent fans out each wave in order:
+
+1. **Create an isolated git worktree** for each task in the current wave:
+
+   ```bash
+   git worktree add ../worktrees/agent-<task-id> -b agent/<task-id>
+   ```
+
+2. **Spawn a task agent** inside that worktree (using the approved model from
+   the split plan), with:
+   - The task id, summary, and acceptance criteria as its brief.
+   - Instruction to work **test-first** (TDD): write the failing test(s) that
+     match the acceptance criteria before implementing.
+   - Instruction to commit its work to the worktree branch.
+
+3. **Same-wave tasks run in parallel** (within-wave tasks have no
+   inter-task dependency; the dependency graph guarantees this). Same-file
+   overlap surfaces as a merge conflict at reconcile time, not a live race —
+   isolated worktrees prevent clobbering.
+
+4. **Wait for all tasks in the wave to complete** before starting the next wave.
+
+### TDD-gated merge — main agent, no human per task
+
+For each completed task worktree, the main agent:
+
+1. **Runs the task's tests before merge** (on the main branch): baseline must
+   pass (or the relevant tests must be absent — the task adds them).
+2. **Merges the worktree branch** into the main branch:
+
+   ```bash
+   git merge --no-ff agent/<task-id>
+   ```
+
+3. **Runs the task's tests after merge**: they must pass. If they do not, the
+   merge is reverted and the task agent is given the failure output to fix.
+4. **Removes the worktree** once the merge is accepted:
+
+   ```bash
+   git worktree remove ../worktrees/agent-<task-id>
+   ```
+
+The human does **not** review individual task merges. Per-task acceptance is
+the main agent's responsibility — the TDD gate (tests pass before AND after
+merge) plus the task's acceptance criteria. This mirrors the non-authoritative
+working state pattern of the Human Review Loop (#17): per-task merge records
+are uncommitted working state; the authoritative human gate is the final PR.
+
+Advance to the next wave only after all tasks in the current wave are merged
+and their tests pass.
+
+### Human gate 3 — the final PR
+
+Once all waves are merged and the full test suite passes, the main agent opens
+a PR via the `cicd` skill (`agex pr open`). The human reviews and merges. This
+is the last and only remaining human gate.
+
+## Hard rules (do not violate)
+
+These protect the human-gate contract and the TDD guarantee.
+
+- **Present the split plan before any fan-out.** Never spawn a task agent
+  without prior human approval of the implementation split plan (gate 2). The
+  split plan is the human's only implementation-stage decision.
+- **One worktree per task.** Never run two tasks in the same worktree — file
+  contention is managed by isolation, not by trust in the dependency graph.
+  The dependency graph guarantees *logical* independence within a wave, not
+  *file* disjointness. Conflicts surface at merge time.
+- **Tests before AND after merge — no exceptions.** The TDD gate must pass on
+  both sides. A merge that makes tests pass only after (not before) means the
+  baseline was already broken — fix the baseline first.
+- **Human does not gate per-task merges.** The TDD contract replaces the
+  human here. Do not pause for human approval between wave tasks.
+- **devague CLI is not orchestrated.** `devague plan waves` is read-only
+  scheduling metadata (#20). Never run `devague plan` commands inside a task
+  worktree to "mark a task done" or modify plan state from a subagent.
+- **Three gates only.** The human's gates are: (1) the exported spec, (2) the
+  implementation split plan, (3) the final PR. No silent fourth gate.
+- **No LLM calls in the devague CLI.** The CLI is deterministic. This skill
+  adds orchestration convention, not CLI behavior.
+
+## Output contract
+
+The `split-plan` subcommand prints to **stdout** and exits 0 when a converged
+plan is found. On error (no plan, cyclic graph) it exits non-zero with a
+`hint:` line on stderr. The `waves` subcommand forwards the CLI's own output
+contract (stdout, `--json` for structured output, exit 0 on success).
+
+## Worked example
+
+Picking up after `/spec-to-plan` exported a plan for the frame `my-feature`:
+
+```bash
+a() { bash .claude/skills/assign-to-workforce/scripts/assign-to-workforce.sh "$@"; }
+
+# 1. Inspect the waves
+a waves
+
+# 2. Present the implementation split plan for human review
+a split-plan
+
+# --- HUMAN: review the table, edit agent/model assignments if needed,
+#     then say "approved" to proceed ---
+
+# 3. Fan out wave 1 (t1, t2, t3 are independent — run in parallel)
+git worktree add ../worktrees/agent-t1 -b agent/t1
+git worktree add ../worktrees/agent-t2 -b agent/t2
+git worktree add ../worktrees/agent-t3 -b agent/t3
+# ... spawn task agents in each worktree, await completion ...
+
+# 4. TDD-gated merge for each wave-1 task (no human per task)
+git merge --no-ff agent/t1   # tests pass before + after
+git worktree remove ../worktrees/agent-t1
+git merge --no-ff agent/t2
+git worktree remove ../worktrees/agent-t2
+git merge --no-ff agent/t3
+git worktree remove ../worktrees/agent-t3
+
+# 5. Advance to wave 2 (t4 depends on t1–t3 being merged)
+git worktree add ../worktrees/agent-t4 -b agent/t4
+# ... spawn, await, merge with TDD gate, remove worktree ...
+
+# 6. Open the final PR (human gate 3)
+bash .claude/skills/cicd/scripts/workflow.sh open
+```
+
+The exported plan-md from `devague plan export` is the standing brief for
+each task agent — its task id, summary, acceptance criteria, and the targets
+it covers are already in that file.
+
+## Provenance
+
+This is a **first-party** skill — its origin is `agentculture/devague`, where
+the devague agent maintains it alongside the tools it operates (dogfooding),
+next to its siblings `/think` and `/spec-to-plan`. It is the *third* skill in
+that outbound family, covering the implementation leg after a plan converges.
+The flow runs the *opposite* direction of the vendored steward skills: steward
+pulls this **from** devague and broadcasts it to the rest of the AgentCulture
+mesh. The `cite, don't import` policy still holds: downstream repos copy it,
+they don't symlink or depend on it. See `docs/skill-sources.md`.