guild-cli 0.5.1__tar.gz → 0.6.0__tar.gz

{guild_cli-0.5.1 → guild_cli-0.6.0}/.claude/skills/guild/SKILL.md

@@ -1,18 +1,19 @@
 ---
 name: guild
 description: >
-  Run guildmaster's skills-supplier overview and narrate it. Run `guild
-  overview` (via scripts/overview.sh) for the deterministic evidence pack — the
-  canonical skill set + versions/origins, the docs/skill-sources.md ledger, and
-  skills-scoped drift signals — then narrate three separated layers: observed
-  facts, inferred relationships, and suggestions (each naming the command that
-  enacts it). Use when an operator asks "what skills do we supply", "who
-  consumes what", "is anything drifting", or "what should I teach next".
-  Skills-scoped and reflect-only — it surfaces and interprets supplier-side
-  skill/version signals; it does NOT narrate the agent relationship graph or
-  judge alignment (that stays with steward's org-overview / steward doctor).
-  The skills-scoped excerpt of steward's `org-overview` narration contract
-  (cite-don't-import, issue #12).
+  Run guildmaster's skills-supplier CLI surfaces and narrate them. Covers
+  `guild overview` (evidence pack: canonical skill set + ledger + drift),
+  `guild create` (provision a new sibling repo by instantiating the template),
+  and `guild show` (one agent's config). Run the matching script for
+  deterministic evidence, then narrate three separated layers: observed facts,
+  inferred relationships, and suggestions (each naming the command that enacts
+  it). Use when an operator asks "what skills do we supply", "provision a new
+  agent", "who consumes what", "is anything drifting", or "what should I teach
+  next". Skills-scoped and reflect-only for overview/show; create is a write
+  verb (dry-run by default, --apply executes). Does NOT narrate the agent
+  relationship graph or judge alignment (steward's lane). The skills-scoped
+  excerpt of steward's `org-overview` narration contract (cite-don't-import,
+  issue #12).
 type: command
 ---
 
@@ -72,7 +73,7 @@ without waiting for the cutover. Still skills-scoped — no relationship graph.
 - "What should I `teach` next?" — overview's gaps are the input to `teach`.
 - Before `guild teach` / `guild onboard`, to see uncovered skills and kit gaps.
 
-## How to run
+## How to run `guild overview`
 
 One script. Pick the scope (or just run `guild overview`, which this wraps):
 
@@ -91,6 +92,64 @@ One script. Pick the scope (or just run `guild overview`, which this wraps):
 .claude/skills/guild/scripts/overview.sh --scope mesh --json
 ```
 
+## How to run `guild create`
+
+Provision a new sibling by instantiating the GitHub template and customising it:
+
+```bash
+# Dry-run — renders the rename plan + ledger diff, performs nothing external
+.claude/skills/guild/scripts/create.sh \
+    --agent agentculture/new-agent \
+    --desc "A short description of the new agent."
+
+# --apply — actually creates the repo, clones, transforms, pushes, registers
+.claude/skills/guild/scripts/create.sh \
+    --agent agentculture/new-agent \
+    --desc "A short description." \
+    --apply
+
+# Custom template or backend
+.claude/skills/guild/scripts/create.sh \
+    --agent agentculture/new-agent \
+    --desc "An ACP agent." \
+    --backend acp \
+    --template myorg/my-template \
+    --apply
+
+# JSON output (works in both dry-run and apply)
+.claude/skills/guild/scripts/create.sh \
+    --agent agentculture/new-agent \
+    --desc "Machine-readable output." \
+    --json
+```
+
+### What `guild create` does
+
+1. Instantiates `agentculture/culture-agent-template` (or `--template`) via
+   `gh repo create --template`.
+2. Clones the new repo into `<workspace-root>/<bare>`.
+3. Runs the **pure transform** on the clone:
+   - global text replace: `culture_agent_template` → pkg, `culture-agent-template` → repo token
+   - renames the package directory
+   - sets `description` in `pyproject.toml`
+   - rewrites `README.md` first heading + intro
+   - overwrites `CLAUDE.md` with a self-init seed (names the agent, embeds the
+     description, carries a `/init` re-init instruction)
+4. Runs `configure-repo.sh` to apply GitHub settings (branch protection,
+   environments, `SONAR_TOKEN` placeholder).
+5. Stages, commits (`scaffold <bare> from culture-agent-template`), and pushes.
+6. Registers the new agent in `docs/skill-sources.md` (idempotent).
+
+Dry-run (default) performs steps 1–5 as a plan description only — nothing
+external. `--apply` executes all steps.
+
+### When to use
+
+- Provisioning a brand-new AgentCulture sibling repo.
+- Before `guild onboard` (create the repo first, then onboard the skill kit).
+- The new agent gets a `/init` seed CLAUDE.md; run `/init` in the new repo to
+  expand it into a full runtime prompt.
+
 The script prints the CLI's markdown by default: the canonical-skill table, a
 ledger section, and a drift section. The exact per-skill consumer and gap lists
 live in `--json`.

guild_cli-0.6.0/.claude/skills/guild/scripts/configure-repo.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# configure-repo — apply guildmaster's standard GitHub repo config to a sibling.
+#
+# GitHub template instantiation copies files + branches but NOT repo settings,
+# so `guild create` must apply these itself after the repo exists. This is the
+# deterministic config layer, mirroring guildmaster's own setup:
+#
+#   1. delete_branch_on_merge = true   (auto-delete head branches on merge)
+#   2. environments: pypi, testpypi    (Trusted Publishing targets for publish.yml)
+#   3. ruleset "Protect main"          (block deletion + non-fast-forward; require a PR)
+#   4. secret SONAR_TOKEN              (created EMPTY if absent; never clobbers an
+#                                       existing value — override it in the GitHub UI)
+#
+# Idempotent: the ruleset is created only if no ruleset of that name exists, and
+# the secret is set only if it is not already present. Dry-run by default.
+#
+# Usage:
+#   configure-repo.sh <owner/repo>            # dry-run: print what it WOULD do
+#   configure-repo.sh <owner/repo> --apply    # apply via gh
+#
+# Exit codes: 0 success · 1 usage / environment error.
+
+RULESET_NAME="Protect main"
+SONAR_SECRET="SONAR_TOKEN"
+ENVIRONMENTS=(pypi testpypi)
+
+repo=""
+apply=false
+for arg in "$@"; do
+    case "$arg" in
+        --apply) apply=true ;;
+        -*) echo "configure-repo: unknown flag: $arg" >&2; exit 1 ;;
+        *) repo="$arg" ;;
+    esac
+done
+
+if [ -z "$repo" ]; then
+    echo "usage: configure-repo.sh <owner/repo> [--apply]" >&2
+    exit 1
+fi
+command -v gh >/dev/null 2>&1 || { echo "configure-repo: 'gh' not on PATH" >&2; exit 1; }
+
+say() { if $apply; then echo "  ✓ $1"; else echo "  would: $1"; fi; }
+
+echo "── configure-repo: $repo $([ "$apply" = true ] && echo '(--apply)' || echo '(dry-run)') ──"
+
+# 1. auto-delete-on-merge ---------------------------------------------------
+say "set delete_branch_on_merge = true"
+if $apply; then
+    gh api -X PATCH "repos/$repo" -F delete_branch_on_merge=true >/dev/null
+fi
+
+# 2. environments -----------------------------------------------------------
+for env in "${ENVIRONMENTS[@]}"; do
+    say "ensure environment '$env'"
+    if $apply; then
+        gh api -X PUT "repos/$repo/environments/$env" >/dev/null
+    fi
+done
+
+# 3. ruleset "Protect main" (idempotent by name; no gh calls in dry-run) -----
+if ! $apply; then
+    echo "  would: ensure ruleset '$RULESET_NAME' (deletion + non_fast_forward + pull_request; created if absent)"
+elif gh api "repos/$repo/rulesets" --jq '.[].name' 2>/dev/null | grep -Fxq "$RULESET_NAME"; then
+    echo "  • ruleset '$RULESET_NAME' already present — skipping"
+else
+    echo "  ✓ create ruleset '$RULESET_NAME' (deletion + non_fast_forward + pull_request)"
+    gh api -X POST "repos/$repo/rulesets" --input - >/dev/null <<JSON
+{
+  "name": "$RULESET_NAME",
+  "target": "branch",
+  "enforcement": "active",
+  "conditions": { "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] } },
+  "rules": [
+    { "type": "deletion" },
+    { "type": "non_fast_forward" },
+    { "type": "pull_request",
+      "parameters": {
+        "required_approving_review_count": 0,
+        "dismiss_stale_reviews_on_push": false,
+        "require_code_owner_review": false,
+        "require_last_push_approval": false,
+        "required_review_thread_resolution": false
+      }
+    }
+  ]
+}
+JSON
+fi
+
+# 4. SONAR_TOKEN secret (empty placeholder; never clobber an override) -------
+if ! $apply; then
+    echo "  would: ensure secret '$SONAR_SECRET' (created empty if absent; never clobbers an override)"
+elif gh secret list --repo "$repo" 2>/dev/null | grep -q "^${SONAR_SECRET}\b"; then
+    echo "  • secret '$SONAR_SECRET' already set — leaving it (override lives in GitHub)"
+else
+    echo "  ✓ create empty secret '$SONAR_SECRET' (override it in the GitHub UI)"
+    printf '' | gh secret set "$SONAR_SECRET" --repo "$repo" >/dev/null
+fi
+
+echo "── done ──"

guild_cli-0.6.0/.claude/skills/guild/scripts/create.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# create — invoke `guild create` from guildmaster's repo root.
+#
+# Instantiates agentculture/culture-agent-template (or a caller-supplied
+# --template) for a new sibling agent, renames identifiers, writes a self-init
+# CLAUDE.md seed, configures the GitHub repo, pushes the genesis commit, and
+# registers the agent in docs/skill-sources.md.
+#
+# Dry-run by default; --apply executes.
+#
+# Usage:
+#   create.sh --agent OWNER/REPO --desc TEXT [--backend claude|acp]
+#             [--workspace-root DIR] [--template OWNER/REPO]
+#             [--org agentculture] [--apply] [--json]
+#
+# Exit codes:
+#   0   success (delegates to `guild create`; its exit code propagates)
+#   1   environment error (no way to invoke guild)
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Resolve guildmaster's repo root.
+REPO_ROOT="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null || true)"
+if [ -z "$REPO_ROOT" ]; then
+    REPO_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+fi
+cd "$REPO_ROOT"
+
+# Resolve how to invoke guild.
+if command -v guild >/dev/null 2>&1; then
+    GUILD=(guild)
+elif [ -f "$REPO_ROOT/pyproject.toml" ] && command -v uv >/dev/null 2>&1; then
+    GUILD=(uv run --project "$REPO_ROOT" guild)
+elif command -v python3 >/dev/null 2>&1; then
+    GUILD=(python3 -m guild)
+else
+    echo "create: cannot invoke guild (need 'guild', 'uv', or 'python3' on PATH)" >&2
+    exit 1
+fi
+
+exec "${GUILD[@]}" create "$@"

{guild_cli-0.5.1 → guild_cli-0.6.0}/.gitignore

@@ -222,3 +222,6 @@ __marimo__/
 
 # devague working state (not committed by default)
 .devague/reviews/
+
+# agex (cicd) per-checkout working dir
+.agex/

{guild_cli-0.5.1 → guild_cli-0.6.0}/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-05-26
+
+### Added
+
+- **`guild create` — template-instantiate a new sibling repo.** Provisions a
+  brand-new AgentCulture sibling by instantiating
+  `agentculture/culture-agent-template` (overridable via `--template`),
+  renaming identifiers throughout the clone (`culture_agent_template` → pkg,
+  `culture-agent-template` → repo token), writing a self-init CLAUDE.md seed
+  (carries a `/init` re-init instruction; satisfies `steward doctor`
+  prompt-file-present + backend-consistency invariants), configuring the GitHub
+  repo via `configure-repo.sh`, pushing the genesis commit, and registering the
+  agent in `docs/skill-sources.md` (idempotent). Dry-run by default; `--apply`
+  executes. `--json` emits a structured payload on both paths.
+  - `guild/scaffold/instantiate.py` — the **pure** transform: `rename_map`,
+    `transform_plan` (dry-run description), `transform_clone` (in-place);
+    no network, no subprocess, fully unit-testable against a fixture dir.
+  - `guild/cli/_commands/_provision_template.py` — injectable-runner executor
+    with `preflight` (fail-fast: auth, existence, empty dest) and `apply`
+    (gh→clone→transform→configure→commit→push).
+  - `guild/cli/_commands/create.py` — CLI verb wiring argparse → plan → render
+    | apply.
+  - `.claude/skills/guild/scripts/create.sh` — thin wrapper (mirrors
+    `overview.sh`).
+  - 39 new tests covering: transform correctness, package-dir rename,
+    identifier replacement everywhere, CLAUDE.md seed shape, dry-run
+    external-free guarantee, `--apply` command sequence, fail-fast on existing
+    repo / no auth / non-empty dest, ledger idempotency.
+
 ## [0.5.1] - 2026-05-24
 
 ### Changed

{guild_cli-0.5.1 → guild_cli-0.6.0}/CLAUDE.md

@@ -106,6 +106,10 @@ asked for one; guildmaster fulfills the broadcast *role* via these two instead).
 Going live is gated on the steward→guildmaster cutover (`docs/cutover.md`) — no
 two live broadcasters.
 
+**Provisioning verb — `guild create` (template-instantiate a new sibling).**
+
+- `guild create --agent OWNER/REPO --desc TEXT [--backend claude|acp] [--workspace-root DIR] [--template agentculture/culture-agent-template] [--apply] [--json]` — provision a brand-new AgentCulture sibling by instantiating the GitHub template, renaming identifiers throughout the clone, writing a self-init CLAUDE.md seed, configuring the GitHub repo (branch protection, environments, SONAR_TOKEN placeholder), pushing the genesis commit, and registering the agent in `docs/skill-sources.md`. Dry-run by default; `--apply` executes. The transform is **pure** (unit-testable against a fixture dir; no network): `culture_agent_template` → pkg (underscore form, e.g. `my_agent`), `culture-agent-template` → repo token (hyphen form, e.g. `my-agent`). The CLAUDE.md seed is a `/init`-style bootstrap placeholder — run `/init` in the new repo after provisioning to expand it into a full runtime prompt. Implementation: `guild/scaffold/instantiate.py` (pure transform), `guild/cli/_commands/create.py` (CLI), `guild/cli/_commands/_provision_template.py` (injectable-runner executor), `.claude/skills/guild/scripts/create.sh` (thin wrapper).
+
 **Inventory verbs — `overview` & `show` (the read-only surfaces).** guildmaster
 owns the mesh's *inventory* surfaces per
 [issue #12](https://github.com/agentculture/guildmaster/issues/12) — the

{guild_cli-0.5.1 → guild_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: guild-cli
-Version: 0.5.1
+Version: 0.6.0
 Summary: guildmaster — an agent and CLI that manages skills for the AgentCulture mesh.
 Project-URL: Homepage, https://github.com/agentculture/guildmaster
 Project-URL: Issues, https://github.com/agentculture/guildmaster/issues

{guild_cli-0.5.1 → guild_cli-0.6.0}/guild/cli/__init__.py

@@ -32,6 +32,7 @@ class _GuildArgumentParser(argparse.ArgumentParser):
 def _build_parser() -> argparse.ArgumentParser:
     # Deferred import to avoid coupling the parser module to the command modules
     # at import time (matches the afi-cli pattern; cheap insurance).
+    from guild.cli._commands import create as _create_cmd
     from guild.cli._commands import explain as _explain_cmd
     from guild.cli._commands import learn as _learn_cmd
     from guild.cli._commands import onboard as _onboard_cmd
@@ -56,6 +57,7 @@ def _build_parser() -> argparse.ArgumentParser:
     _explain_cmd.register(sub)
     _teach_cmd.register(sub)
     _onboard_cmd.register(sub)
+    _create_cmd.register(sub)
     _overview_cmd.register(sub)
     _show_cmd.register(sub)
 

{guild_cli-0.5.1 → guild_cli-0.6.0}/guild/cli/_commands/__init__.py

@@ -25,6 +25,11 @@ VERBS: dict[str, str] = {
         "Onboard a new sibling: the full canonical kit + identity-setup section "
         "+ ledger registration + verification record. Dry-run by default."
     ),
+    "create": (
+        "Provision a brand-new sibling repo by instantiating the GitHub template "
+        "agentculture/culture-agent-template, customising it for the new agent, "
+        "and registering it in the ledger. Dry-run by default; --apply executes."
+    ),
     "overview": (
         "Skills-supplier overview — the canonical skill set + versions, the "
         "ledger view, and drift signals. Read-only; --scope all / self."