@shiftingcroco/crocodeur

@shiftingcroco/crocodeur

Méta-harnais SDLC spec-driven portable — CLI init / sync / upgrade + cœur CDA (step / pipeline / spec / session / artifact) + pont issues framework. Package public publié sur npm (0.x, semver dès la v1).

Crocodeur matérialise un harnais d'agents IA complet dans n'importe quel dépôt hôte : un home .crocodeur/ (builtins + overrides local/ + état vivant), des adaptateurs de harnais générés (.claude/, .opencode/, .mcp.json = sorties committées de crocodeur sync), et un cœur Contract-Driven Agents utilisable hors ligne pour piloter /brief → /spec → /plan → /execute.

Installation

Le package est public sur npm (registry.npmjs.org). Le scope @shiftingcroco se résout anonymement : aucun token, aucun .npmrc n'est requis pour l'installer. L'install réussit du premier coup.

1. Installer

pnpm add -D @shiftingcroco/crocodeur   # (npm i -D / yarn add -D équivalents)

Le package requiert Node >= 20 (aligné .nvmrc).

Si l'install échoue, classe le code d'erreur avant de provisionner quoi que ce soit : un 404 signifie que le scope n'est pas résolu (souvent un ~/.npmrc privé qui détourne @shiftingcroco — le retirer, jamais poser un token) ; seul un 401/403 justifie un credential. Doctrine complète : ONBOARDING.md §Étape 1.

2. Initialiser le harnais

pnpm exec crocodeur init      # scaffold .crocodeur/ + premier sync (repo vierge)
pnpm exec crocodeur sync      # régénère .claude/ + .opencode/ + .mcp.json

init refuse un dépôt non-vierge par défaut (.claude/ / .opencode/ préexistants) ; --force traite l'existant comme des sorties à régénérer. Exit codes : 0 = succès/no-op, 1 = refus/erreur (toutes commandes) ; seul init (et upgrade) ajoute 2 = divergence hôte (builtin modifié à la main). Détail : crocodeur --help.

Pont issues framework (crocodeur issue)

Remonter une issue du framework (bug harnais, tech-debt, amélioration) vers le tracker dédié ShiftingCroco/crocodeur — jamais vers le backlog produit de l'hôte, jamais avec du contexte client (le body passe par un template sanitisé qui rédige tout secret).

Auth — CROCODEUR_ISSUE_TOKEN

export CROCODEUR_ISSUE_TOKEN="<PAT fine-grained, scope issues: write sur ShiftingCroco/crocodeur>"

Préséance de résolution : CROCODEUR_ISSUE_TOKEN → GH_TOKEN → GITHUB_TOKEN (les deux derniers ne servent de repli que s'ils portent le scope issues: write). Aucun token trouvé ⇒ échec immédiat (exit 1) avec un message pointant cette section — jamais de POST aveugle.

Usage

crocodeur issue create \
  --title "Titre concis de l'issue framework" \
  --body  "Description (ou --body-file <chemin> / --body-file - pour stdin)" \
  --label bug --label ai-detected      # --label répétable

# Prévisualiser la requête POST sans rien envoyer (aucun réseau) :
crocodeur issue create --title "…" --body "…" --dry-run

Sortie succès : JSON { "number": <n>, "html_url": "<url>" } sur stdout.

Le pont issues est la seule commande réseau du package, à l'initiative de l'opérateur. init / sync / upgrade restent 100 % hors ligne.

Publication (mainteneurs)

La publication est publique (publishConfig.access: public, registre registry.npmjs.org) et jamais automatique : elle se déclenche uniquement en manuel / sur release via le workflow crocodeur-release.yml. Le CI de release exécute d'abord un secret-scan du tarball (npm pack → extraction → détecteurs) et un smoke-install L3 déterministe (repo tmp vierge → install tarball → init → vérif manifest + checksums → sync --check (+ 2e run, déterminisme) → scaffold direct d'un spec.state.json minimal → validate → step claim → frontière namespace hôte) avant tout publish. Le spec portable n'expose que status / claim / resume (aucun verbe create — le scaffold du spec.state.json est direct).

Références

• Spec SSOT : docs/specs/20260707-crocodeur-package-extraction/
• Doctrine méta-harnais : docs/crocodeur/README.md