yadflow 1.0.1

package/cli/setup.mjs

@@ -0,0 +1,208 @@
+// `sdlc setup` — the guided, idempotent first-run wizard.
+import path from 'node:path';
+import fs from 'node:fs';
+import {
+  c, log, step, ok, info, warn, hand, fail, ask, askYesNo, run, has,
+  exists, asset, copyFile, readJSON, writeJSON,
+} from './lib.mjs';
+import { VERSION, IDE_FOLDER_TARGETS, IDE_OPENCODE_DIR, PROJECT_FILES } from './manifest.mjs';
+import { moduleActions, repoActions, hubActions, authorsActions } from './plan.mjs';
+
+const ALL_IDES = [...IDE_FOLDER_TARGETS, '.opencode'];
+
+export function detectPlatform(remoteUrl = '') {
+  if (/gitlab/i.test(remoteUrl)) return 'gitlab';
+  if (/github/i.test(remoteUrl)) return 'github';
+  return null;
+}
+export const gitHead = (cwd) => run('git', ['rev-parse', 'HEAD'], { cwd }).stdout || null;
+
+// Containment: every repo path must live inside the project root — the registry path is later
+// joined and executed against (repomix cwd, CI wiring), and even the read-only remote probe must
+// not run against an arbitrary outside path. The path.sep-suffixed compare avoids the
+// /proj vs /proj-evil prefix trap.
+export function insideRoot(root, rpath) {
+  const projectRoot = path.resolve(root);
+  const resolved = path.resolve(projectRoot, rpath);
+  return resolved === projectRoot || resolved.startsWith(projectRoot + path.sep);
+}
+
+// Validate + record one code repo into the registry (the testable half of the connect loop).
+// A path that is not a git repository is rejected and NOTHING is written — a registry entry with
+// syncedHead:null would only surface later as an unexplained "unknown status" in the CI gates.
+export function registerRepo(root, registry, { name, rpath, platform, domain_owner = '', default_branch = 'main', today = null }) {
+  if (!insideRoot(root, rpath)) {
+    warn(`${rpath} resolves outside the project root — skipped`);
+    return null;
+  }
+  const repoRoot = path.resolve(root, rpath);
+  const head = gitHead(repoRoot);
+  if (head === null) { warn(`${rpath} is not a git repository (or has no commits) — skipped`); return null; }
+  const remote = run('git', ['remote', 'get-url', 'origin'], { cwd: repoRoot });
+  let plat = (platform || '').toLowerCase();
+  if (!['github', 'gitlab'].includes(plat)) {
+    const detected = detectPlatform(remote.ok ? remote.stdout : '') || 'github';
+    if (plat) warn(`unknown platform '${platform}' — using ${detected}`);
+    plat = detected;
+  }
+  const repo = {
+    name, path: rpath, git_url: (remote.ok && remote.stdout) || null, platform: plat, domain_owner, default_branch,
+    connectedAt: today, lastSyncedAt: today,
+    syncedHead: head,
+    contextPack: `.sdlc/code-context/${name}/pack.md`,
+    codeMap: `.sdlc/code-context/${name}/code-map.md`,
+    source: 'repomix',
+  };
+  registry.repos.push(repo);
+  writeJSON(path.join(root, PROJECT_FILES.reposRegistry), registry);
+  return repo;
+}
+
+function applyActions(actions, { force = false } = {}) {
+  let changed = 0;
+  for (const a of actions) {
+    if (a.status === 'ok' && !force) continue;
+    a.apply();
+    changed++;
+    info(`${a.status === 'missing' ? 'installed' : 'updated'} ${a.scope}/${a.item}`);
+  }
+  if (!changed) info('already up to date');
+  return changed;
+}
+
+export async function runSetup(root, opts = {}) {
+  const total = 7;
+  log(c.bold(`\nSDLC Workflow setup  ${c.dim('v' + VERSION)}`));
+  log(c.dim(`target: ${root}`));
+
+  // 1. Preflight
+  step(1, total, 'Preflight');
+  if (!exists(path.join(root, '.git'))) {
+    if (await askYesNo('Not a git repo. Run `git init` here?', true)) {
+      run('git', ['init'], { cwd: root });
+      ok('git initialized');
+    } else warn('continuing without git — hub detection will be skipped');
+  } else ok('git repo detected');
+  for (const tool of ['git', 'node']) has(tool) ? ok(`${tool} present`) : warn(`${tool} not found on PATH`);
+  if (!has('npx')) warn('npx not found — repomix packing will be skipped');
+
+  // 2. Install the module
+  step(2, total, 'Install the module (skills + _bmad registration)');
+  let ideTargets = opts.ideTargets;
+  if (!ideTargets) {
+    const present = ALL_IDES.filter((d) => exists(path.join(root, d)));
+    const def = (present.length ? present : ['.claude']).join(',');
+    const answer = await ask(`IDE targets to install ${c.dim('(comma-separated: ' + ALL_IDES.join(', ') + ')')}`, def);
+    ideTargets = answer.split(',').map((s) => s.trim()).filter(Boolean);
+  }
+  applyActions(moduleActions(root, ideTargets), { force: true });
+  ok(`module installed into: ${ideTargets.join(', ')}`);
+
+  // 3. Detect hub platform + roster
+  step(3, total, 'Hub platform & reviewer roster');
+  const hubPath = path.join(root, PROJECT_FILES.hubConfig);
+  if (exists(hubPath) && !(await askYesNo('hub.json exists — reconfigure?', false))) {
+    info('keeping existing .sdlc/hub.json');
+  } else {
+    const remote = run('git', ['remote', 'get-url', 'origin'], { cwd: root });
+    if (!remote.ok && exists(path.join(root, '.git'))) info('no origin remote — platform detection skipped');
+    let platform = detectPlatform(remote.ok ? remote.stdout : '');
+    platform = (await ask('Hub platform (github/gitlab/none)', platform || 'none')).toLowerCase();
+    if (!['github', 'gitlab', 'none'].includes(platform)) {
+      warn(`unknown platform '${platform}' — using none (file-only gate)`);
+      platform = 'none';
+    }
+    const roster = [];
+    if (await askYesNo('Add reviewers to the roster now?', true)) {
+      for (;;) {
+        const login = await ask('  reviewer platform login (blank to finish)', '');
+        if (!login) break;
+        const name = await ask('    sdlc name', login);
+        const role = await ask('    role (owner/reviewer/domain-owner)', 'reviewer');
+        const email = await ask('    commit email (verified-commits gate; blank to skip)', '');
+        roster.push({ login, name, role, ...(email ? { email } : {}) });
+      }
+    }
+    const default_branch = platform === 'none' ? 'main' : await ask('Hub default branch', 'main');
+    // `bridge_enabled` is the canonical flag (hub-config schema); keep the legacy `bridge` spelling
+    // for anything that still reads it.
+    const enabled = platform !== 'none';
+    writeJSON(hubPath, { platform: enabled ? platform : null, bridge_enabled: enabled, bridge: enabled, default_branch, roster });
+    ok(`wrote ${PROJECT_FILES.hubConfig} (${roster.length} reviewer(s))`);
+  }
+
+  // 4. Connect code repos
+  step(4, total, 'Connect code repos');
+  const regPath = path.join(root, PROJECT_FILES.reposRegistry);
+  const registry = readJSON(regPath, { repos: [] });
+  const known = new Set(registry.repos.map((r) => r.name));
+  if (await askYesNo(`Connect a code repo? ${c.dim(`(${registry.repos.length} already registered)`)}`, registry.repos.length === 0)) {
+    for (;;) {
+      const name = await ask('  repo name (blank to finish)', '');
+      if (!name) break;
+      if (known.has(name)) { warn(`${name} already registered — skipping`); continue; }
+      const rpath = await ask('    path (relative to project root)', `demo-repos/${name}`);
+      if (!insideRoot(root, rpath)) { warn(`${rpath} resolves outside the project root — skipped`); continue; }
+      const detected = run('git', ['remote', 'get-url', 'origin'], { cwd: path.resolve(root, rpath) });
+      const platform = (await ask('    platform (github/gitlab)', detectPlatform(detected.ok ? detected.stdout : '') || 'github')).toLowerCase();
+      const domain_owner = await ask('    domain owner', '');
+      const default_branch = await ask('    default branch', 'main');
+      const repo = registerRepo(root, registry, { name, rpath, platform, domain_owner, default_branch, today: opts.today ?? null });
+      if (!repo) continue;
+      known.add(name);
+      ok(`registered ${name}`);
+      packRepo(root, repo);
+    }
+  }
+
+  // 5. Wire each connected repo + the hub itself
+  step(5, total, 'Wire connected repos + the hub (CI gates, PR template, comment scaffold, gate-sync)');
+  if (registry.repos.length === 0) info('no repos to wire');
+  for (const repo of registry.repos) {
+    log(`  ${c.bold(repo.name)} ${c.dim(`(${repo.platform})`)}`);
+    applyActions(repoActions(root, repo), { force: true });
+  }
+  // the hub: event-driven gate-sync CI, so platform approvals/merges drive `sdlc gate ci`
+  const hubWiring = hubActions(root);
+  if (hubWiring.length) {
+    log(`  ${c.bold('hub')} ${c.dim('(gate-sync + verified-commits CI)')}`);
+    applyActions(hubWiring, { force: true });
+  }
+  // author allowlists for the verified-commits gate (hub + every repo), from the roster emails
+  applyActions(authorsActions(root, registry.repos), { force: true });
+
+  // 6. Optional CodeRabbit
+  step(6, total, 'AI review (CodeRabbit)');
+  for (const repo of registry.repos) {
+    const cr = path.join(path.resolve(root, repo.path), '.coderabbit.yaml');
+    if (exists(cr)) { info(`${repo.name}: .coderabbit.yaml present`); continue; }
+    if (await askYesNo(`Wire CodeRabbit (advisory) in ${repo.name}?`, false)) {
+      fs.writeFileSync(cr, 'reviews:\n  high_level_summary: true\n  poem: false\n');
+      ok(`${repo.name}: wrote .coderabbit.yaml`);
+    }
+  }
+
+  // 7. Summary + version stamp
+  step(7, total, 'Done');
+  writeJSON(path.join(root, PROJECT_FILES.version), { version: VERSION, ideTargets, updatedAt: opts.today ?? null });
+  ok(`stamped ${PROJECT_FILES.version} (v${VERSION})`);
+  log('');
+  log(c.bold('Next — AI-only steps (run in Claude Code):'));
+  hand('generate code-maps: run `sdlc-connect-repos` for each connected repo');
+  hand('author your first epic: run `sdlc-author-epic`');
+  log('');
+  log(c.dim('Re-run anytime: `sdlc check` (report) / `sdlc check --fix` (reconcile).'));
+}
+
+// Deterministic repomix pack (code-map generation itself is an AI step, handed off).
+export function packRepo(root, repo) {
+  const repoRoot = path.resolve(root, repo.path);
+  const out = path.join(root, repo.contextPack);
+  if (!has('npx')) { warn(`${repo.name}: npx missing — skipped repomix pack`); return false; }
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  info(`${repo.name}: packing with repomix …`);
+  const r = run('npx', ['repomix@latest', '--compress', '--include-logs', '--style', 'markdown', '-o', out], { cwd: repoRoot });
+  if (r.ok) { ok(`${repo.name}: cached ${repo.contextPack}`); hand(`${repo.name}: generate the code-map in Claude Code (sdlc-connect-repos)`); return true; }
+  fail(`${repo.name}: repomix failed — ${r.stderr.split('\n')[0] || 'unknown error'}`);
+  return false;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "yadflow",
+  "version": "1.0.1",
+  "description": "Gated, team, multi-repo SDLC workflow: author → review → build with a PR-driven review gate and a zero-dependency CLI (setup, gate, commit, open-pr, repo). A BMAD module + 17 skills.",
+  "type": "module",
+  "author": "AbdelRahman Nasr",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abdelrahmannasr/sdlc-workflow.git"
+  },
+  "homepage": "https://github.com/abdelrahmannasr/sdlc-workflow#readme",
+  "bugs": {
+    "url": "https://github.com/abdelrahmannasr/sdlc-workflow/issues"
+  },
+  "bin": {
+    "sdlc": "bin/sdlc.mjs"
+  },
+  "files": [
+    "bin/",
+    "cli/",
+    "!cli/test.mjs",
+    "skills/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "sdlc": "node bin/sdlc.mjs",
+    "test": "node --test cli/test.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "sdlc",
+    "bmad",
+    "workflow",
+    "cli",
+    "spec-driven-development"
+  ],
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "semantic-release": "^25.0.3"
+  }
+}

package/skills/sdlc/config.yaml

@@ -0,0 +1,156 @@
+# SDLC Workflow Module Configuration
+# Hand-authored custom BMAD module (format mirrors _bmad/<module>/config.yaml, v6.8.0).
+# Source of truth lives in {project-root}/skills/ and survives BMAD updates.
+
+module_name: sdlc
+module_title: "SDLC Workflow"
+methodology: gated-team-multirepo-sdlc
+
+# Where epic "thinking" artifacts and per-epic state live (the product repo).
+product_root: "{project-root}"
+epics_folder: "{project-root}/epics"
+
+# Core configuration values (inherited convention from _bmad/config.toml).
+project_name: sdlc-workflow
+communication_language: English
+document_output_language: English
+output_folder: "{project-root}/_bmad-output"
+
+# Default dials applied to every new step (build plan §2).
+defaults:
+  assistance: review          # none | review | heavy
+  automation: human_approve   # human_approve | machine_advance
+  # Front steps (analysis [optional], epic, architecture, ui-design, stories) are locked to
+  # human_approve and may NOT be set to machine_advance in this version (build plan §1, §8.7).
+  front_steps_locked: true
+  # Each front authoring step opens its own branch at the start of the step (the <step> is the step id:
+  # analysis | epic | architecture | ui-design | stories). Git/greenfield-safe; distinct from the
+  # bridge's review branch (hub.artifact_branch). See sdlc-author-epic/references/state-schema.md.
+  front_authoring_branch: "<step>/EP-<slug>"
+
+# Team review gate defaults (build plan §3 piece 2, §4).
+review_gate:
+  default_reviewers: 1          # non-owner reviewers required (in addition to 1 owner) => owner + 1 reviewer
+  escalate_when: [contract, auth, payments]   # escalate to domain owners
+  # PR-driven automation (the `sdlc gate` CLI). With a hub platform, the review rides the per-step
+  # PR/MR: `sdlc gate sync` maps platform reviews/threads into the file ledger and the step
+  # AUTO-ADVANCES on merge, once (a) the reviewer rule is met, (b) every comment thread is resolved,
+  # and (c) the review PR/MR is merged. The merge is the human approval act, so front steps still never
+  # machine_advance. The file ledger stays the source of truth; no platform / no gh|glab => file-only.
+  advance_on: merge             # merge of the approved, fully-resolved review PR advances the step
+  revoke_on: artifact-change    # re-hash the artifact (contract surface for architecture); a changed
+                                # hash drops the bound approvals so reviewers re-approve. NOT per-commit.
+  block_on_unresolved_comments: true   # any unresolved thread / CHANGES_REQUESTED holds it in_review
+
+# Build half (Phase 3). Code repos are SEPARATE git repos (one .git each), not subfolders
+# of the product repo — faithful to "per-repo specs in each code repo, contract singular in the
+# product repo" (phase-3-build-plan.md, Cross-cutting). Documentation-as-config for sdlc-spec (Step A).
+build:
+  code_repos_root: "{project-root}/demo-repos"   # throwaway demo code repos for this build half
+  feature_id: story_id          # specs/<story-id>/ — pinned to the permanent story ID, not Spec Kit's auto-slug
+  spec_layout: speckit          # follow Spec Kit's native spec/plan/tasks layout
+  speckit_ceremony: [specify, clarify, plan, analyze, checklist, tasks]   # heavy run, once per story per repo
+  # Step B (sdlc-implement) — the light per-task loop. One atomic task = one branch = one PR/MR.
+  branch_convention: "feat/<story-id>-<task-id>-<short-slug>"   # e.g. feat/EP-istifta-inquiries-S01-T01-create-inquiry
+  commit_task_trailer: "Task: <story-id>-<task-id>"             # final commit trailer; anchors the spec-link check (Step C)
+  contract_change_trailer: "Contract-Change: yes"              # ONLY when the locked contract surface is touched (routes back to architecture gate)
+  # Commit subject + PR/MR title style (Conventional Commits — see CONTRIBUTING.md). PRs are squash-merged,
+  # so the title becomes the subject; both follow one rule. Type lowercase; description lowercase + imperative
+  # + no trailing period; proper nouns/acronyms keep their case.
+  commit_subject_style: "<type>: <lowercase imperative description, no trailing period>"   # types: feat|fix|docs|refactor|test|perf|build|ci|chore|revert
+  pr_title_style: same_as_commit_subject                       # one atomic task = one branch = one PR/MR; title defaults to the task's commit subject
+  # Commit ownership + per-commit AI co-author (sdlc-implement installs the .gitmessage template).
+  # The human git author OWNS the commit; the assisting AI is recorded per-commit as a Co-Authored-By
+  # trailer, chosen by the owner from `ai_coauthor.allowed`. The AI is never the author. `none` is an
+  # explicit human-only choice. Trailer order is Task: -> Contract-Change: (if any) -> Co-Authored-By:.
+  commit_owner: git_author
+  ai_coauthor:
+    trailer: "Co-Authored-By"
+    required: false                  # the trailer is optional; owners pick `none` for human-only commits
+    allowed:
+      - { id: claude,     name: "Claude",             email: "noreply@anthropic.com" }
+      - { id: copilot,    name: "GitHub Copilot",     email: "copilot@users.noreply.github.com" }
+      - { id: cursor,     name: "Cursor",             email: "noreply@cursor.com" }
+      - { id: coderabbit, name: "CodeRabbit",         email: "noreply@coderabbit.ai" }
+      - { id: none,       name: "(no AI assistance)", email: "" }
+  # Step C (sdlc-checks) — the three CI gates that must pass before merge. CI-agnostic bash in checks/.
+  gates: [spec-link, contract-check, build-test-lint]
+  ci_platforms: [github, gitlab]   # both wired from skills/sdlc-checks/templates/; GitHub is this product repo's platform
+  contract_surface_glob: "specs/*/contracts/**"   # the repo's quoted contract slice; a diff here needs Contract-Change + a re-locked contract
+  # Step D (sdlc-pr-template) — platform-matched PR/MR template + risk routing.
+  pr_templates:
+    github: ".github/pull_request_template.md"
+    gitlab: ".gitlab/merge_request_templates/Default.md"
+    hub:                                # front-half artifact-review PR/MR on the product hub (sdlc-pr-template repo:hub)
+      github: ".github/pull_request_template.md"
+      gitlab: ".gitlab/merge_request_templates/Default.md"
+  risk_levels: [low, medium, high]   # high (or a contract/auth/payments surface) routes to domain owners (sdlc-review-gate escalation)
+  # Step E (sdlc-ship) — AI review (advisory) + engineer review (the human gate) + ship.
+  ai_review: coderabbit            # advisory first pass; never the authority (.coderabbit.yaml)
+  build_log: "epics/EP-<slug>/.sdlc/build-log.json"   # append-only ship ledger (back-half analogue of approvals.json)
+  story_build_states: [in-build, shipped]   # in-build = some tasks shipped; shipped = all tasks in tasks.md shipped
+  # Backfill (sdlc-backfill) — specs for already-built features in an existing repo.
+  backfill:
+    tool: repomix                  # the one true CLI subprocess: `npx repomix@latest` (Phase 0 / RESEARCH-NOTES §3)
+    pack_flags: "--compress --include <globs> --include-logs --style markdown"   # one feature at a time; Secretlint by default
+    spec_location: "specs/backfill/<feature>/spec.md"   # draft (verified: false) until a human approves
+    gate_scope: touched-features   # block a change only until the features it touches have approved specs
+
+# Code context (sdlc-connect-repos) — the front/"brain" phases are made code-aware. Code repos are
+# connected to the product hub once (or any time a new repo is added), and an AI-readable picture of
+# each is cached so epic/architecture/ui/stories consider what already exists in the code. The product
+# repo is the FRONT-PHASE TOOLCHAIN HUB: repomix (and Impeccable) are installed/run here and target the
+# connected code repos by path — code repos need no install for this. (The build-half CI gates are the
+# exception: they live INSIDE each code repo and run in that repo's CI — see build.gates above.)
+code_context:
+  registry: "{project-root}/.sdlc/repos.json"        # project-wide repo registry (NOT per-epic)
+  cache_dir: "{project-root}/.sdlc/code-context"      # per-repo pack.md + code-map.md live here
+  tools: [repomix, impeccable]                        # front-phase toolchain, installed in the product hub
+  pack_flags: "--compress --include-logs --style markdown"   # reuse backfill flags; Secretlint by default
+  staleness: head-sha                                 # stale when a repo's HEAD != registry syncedHead
+  refresh: human                                      # a stale repo is a HUMAN decision: front-phase
+                                                      # skills FLAG it and stop (pointing at
+                                                      # `sdlc repo refresh <repo>`) — they never silently
+                                                      # re-pack. `sdlc repo list` shows fresh/stale;
+                                                      # `sdlc repo refresh` and `sdlc check --fix` re-pack.
+  load_in_front_phases: true                          # epic, architecture, ui-design, stories read the maps
+  # Auth: `sdlc-connect-repos` clones/fetches as the LOCAL user (SSH key or git credential helper),
+  # works for both github and gitlab (and self-hosted), and stores NO tokens in the registry.
+  platforms: [github, gitlab]
+
+# Hub platform + front-half review bridge (sdlc-connect-repos `detect-hub`; sdlc-review-gate + sdlc-hub-bridge).
+# The product hub is itself a git repo on a platform. With the bridge enabled, the front-half review/
+# comment/approval cycle runs through a real PR/MR on the hub: a review PR is opened per artifact, reviewers
+# approve/comment on the platform (their own gh/glab auth — NO stored tokens), and `sdlc-review-gate action: sync`
+# pulls that state into the file ledger (approvals.json/reviews/*.md) and runs the UNCHANGED gate predicate.
+# The file ledger stays the source of truth. Degrades to the file-only gate when there is no platform / no CLI.
+hub:
+  config: "{project-root}/.sdlc/hub.json"             # hub platform + reviewer roster (committed, like repos.json)
+  pr_ledger: "{project-root}/epics/EP-<slug>/.sdlc/hub-prs.json"   # per-step review-PR record (sibling of approvals.json)
+  bridge: true                                         # master enable; false => file-only front gates everywhere
+  platforms: [github, gitlab]                          # detected from the hub's own `git remote get-url origin`
+  artifact_branch: "review/EP-<slug>/<artifact-base>"  # branch a review PR is opened on, per artifact
+  # roster (in hub.json) maps a platform login -> sdlc name + role; domain-owners are DERIVED from
+  # repos.json (a roster name that equals a repo's domain_owner owns that repo's domain) — never duplicated.
+
+# Phase 4 (automation) — the SECOND dial made real. Until Phase 4 nothing read this dial; the
+# orchestrator (sdlc-run) now does. Governing rule: automation is EARNED per step, with trust-log
+# evidence, and is reversible in one move (phase-4-build-plan.md §"one principle"). Front states are
+# never listed in back_steps and can never be flipped — the engineer keeps authority over decisions.
+automation:
+  # The only steps that MAY be automated, safest-end first (phase-4-build-plan.md build order).
+  # Phase 4a ships the engine + earns `checks` (Step B). `tasks`/`implement` advance are Phase 4b.
+  back_steps: [spec, tasks, implement, checks]
+  default: human_approve            # every back step starts manual; machine_advance must be earned
+  # A back step is a CANDIDATE for machine_advance only once its trust-log slice clears this bar.
+  # "It seems fine" is not evidence (phase-4-build-plan.md §"Explicitly NOT").
+  trust_threshold:
+    min_runs: 5                     # at least this many recorded runs at the step
+    min_approved_unchanged: 0.8     # >= this fraction "approved-unchanged" over those runs
+  # Hard lock — the dial-setter REFUSES machine_advance for these, regardless of trust evidence.
+  # The front authoring steps (already locked:true in state.json; analysis is optional) + the human
+  # merge gate.
+  locked_steps: [analysis, epic, architecture, ui-design, stories, engineer-review]
+  # Kill switch (phase-4-build-plan.md §Safety): true => every step forced to human_approve
+  # system-wide, no per-step edits. One line, instantly reversible. Toggle via `sdlc-run action: kill`.
+  kill_switch: false

package/skills/sdlc/install.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Install the hand-authored `sdlc` BMAD module into the IDE skill dirs.
+#
+# Source of truth: {project-root}/skills/  (survives `bmad-method` updates).
+# This script copies the sdlc-* skills into the four IDE locations the BMAD installer uses,
+# and registers the module under _bmad/sdlc/. Re-run after any `bmad-method install/update`.
+#
+# Usage:  bash skills/sdlc/install.sh
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$ROOT"
+
+SKILLS=(sdlc-author-analysis sdlc-author-epic sdlc-author-architecture sdlc-author-ui sdlc-author-stories sdlc-connect-repos sdlc-spec sdlc-implement sdlc-checks sdlc-pr-template sdlc-review-comments sdlc-hub-bridge sdlc-ship sdlc-backfill sdlc-run sdlc-review-gate sdlc-status)
+
+echo "Installing sdlc module from $ROOT/skills ..."
+
+# 1. Folder-per-skill IDEs: .claude, .agents, .zencoder
+for ide in .claude .agents .zencoder; do
+  for s in "${SKILLS[@]}"; do
+    if [ -d "skills/$s" ]; then
+      # Remove any stale install first, then copy the whole skill folder
+      # (SKILL.md + references/). rm -rf guarantees no double-nesting on cp -R.
+      rm -rf "$ide/skills/$s"
+      cp -R "skills/$s" "$ide/skills/$s"
+      echo "  $ide/skills/$s"
+    fi
+  done
+done
+
+# 2. opencode: single flat command file per skill (SKILL.md -> commands/<name>.md).
+# Note: opencode commands are flat files, so the skills' references/ folders are
+# NOT carried here. Each SKILL.md is self-contained for its operative rules
+# (schema, gate predicate); references/ only adds supplementary detail.
+if [ -d ".opencode/commands" ]; then
+  for s in "${SKILLS[@]}"; do
+    if [ -f "skills/$s/SKILL.md" ]; then
+      cp "skills/$s/SKILL.md" ".opencode/commands/$s.md"
+      echo "  .opencode/commands/$s.md (references/ not included — flat command)"
+    fi
+  done
+fi
+
+# 3. Register the module under _bmad/sdlc/ (regenerable; _bmad/ is rebuilt on update).
+mkdir -p "_bmad/sdlc"
+cp "skills/sdlc/config.yaml" "_bmad/sdlc/config.yaml"
+cp "skills/sdlc/module-help.csv" "_bmad/sdlc/module-help.csv"
+echo "  _bmad/sdlc/{config.yaml,module-help.csv}"
+
+echo "Done. Skills available: ${SKILLS[*]}"
+echo "Note: _bmad/ is regenerated by BMAD updates — re-run this script afterwards."

package/skills/sdlc/module-help.csv

@@ -0,0 +1,17 @@
+module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
+SDLC Workflow,sdlc-author-epic,Author Epic,AE,"Front state 1: shape an idea with analyst then pm into epic.md; assign EP-<slug> ID and seed .sdlc state. Never auto-advances.",,{idea: one-line feature idea},1-front,,sdlc-review-gate,true,epics/EP-<slug>/,epic.md state.json
+SDLC Workflow,sdlc-review-gate,Team Review Gate,RG,"Reusable review+approve gate for all four reviews. Shares an artifact for review, records comments and approvals as files, enforces owner + 1 reviewer (escalates on contract/auth/payments; per-repo routing for stories), advances state only when approved.",,{artifact: file under the epic} {action: open|comment|approve|advance},1-front,,,true,epics/EP-<slug>/reviews/,reviews/*.md approvals.json state.json
+SDLC Workflow,sdlc-author-architecture,Author Architecture,AA,"Front state 3: with the architect author architecture.md and the locked contract.md; hash-lock the contract surface. Never auto-advances.",,{epic: EP-<slug>},1-front,sdlc-review-gate,sdlc-review-gate,true,epics/EP-<slug>/,architecture.md contract.md contract-lock.json state.json
+SDLC Workflow,sdlc-author-ui,Author UI Design,AU,"Front state 5: with the ux-designer author ui-design.md and DESIGN.md, driving Impeccable slash-commands when installed. Never auto-advances.",,{epic: EP-<slug>},1-front,sdlc-review-gate,sdlc-review-gate,true,epics/EP-<slug>/,ui-design.md DESIGN.md state.json
+SDLC Workflow,sdlc-author-stories,Author Stories,AS,"Front state 7: with the pm break the epic into repo-tagged stories with stable EP-<slug>-S0N IDs, one file each under stories/. Never auto-advances.",,{epic: EP-<slug>},1-front,sdlc-review-gate,sdlc-review-gate,true,epics/EP-<slug>/stories/,stories/EP-<slug>-S0N.md state.json
+SDLC Workflow,sdlc-connect-repos,Connect Code Repos,CR,"Setup/maintenance: connect code repos to the product hub so the front/brain phases are code-aware. Registers each repo (GitHub or GitLab, local-user auth, no stored tokens) in .sdlc/repos.json and caches a Repomix pack + a lightweight code-map (existing endpoints/events/data-models/modules, secret-scanned). Idempotent and refreshable; staleness tracked by HEAD sha. Run at setup or any time a new repo is added. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {repo: <name>} {path: <path-or-absolute>} {git_url: <ssh-or-https>} {domain_owner: <who>},0-setup,,sdlc-author-epic,false,.sdlc/,repos.json code-context/<repo>/pack.md code-context/<repo>/code-map.md
+SDLC Workflow,sdlc-spec,Author Spec,SP,"Build-half Step A: for one ready-for-build story and one of its repos, run the heavy Spec Kit ceremony once (specify→clarify→plan→analyze→checklist→tasks) inside that code repo, writing specs/<story-id>/ in Spec Kit's layout (drives /speckit.* when installed, else hand-authors and records speckit: not-installed). References the locked contract; never re-invents the surface. Writes link.md back to the story. Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {repo: <one of story.repos>},3-build,sdlc-review-gate,,false,demo-repos/<repo>/specs/<story-id>/,spec.md research.md data-model.md contracts/ plan.md tasks.md link.md
+SDLC Workflow,sdlc-implement,Implement Task,IM,"Build-half Step B: with the dev lens, implement ONE atomic task from a story's tasks.md as a small diff (<=3 files) on its own branch feat/<story>-<task>-<slug> in the code repo. Diff stays inside the task's declared files (flag and STOP if it grows beyond them). Commit ends with a Task: <story>-<task> trailer; add Contract-Change: yes only when the locked contract surface is touched (routes back to the architecture gate). Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {repo: <one of story.repos>} {task: T0N},3-build,sdlc-spec,,false,demo-repos/<repo>/,branch+commit per atomic task
+SDLC Workflow,sdlc-checks,Check Gates,CK,"Build-half Step C: wire and run the three production-safety CI gates on a code repo — spec-link (every change links a real story/spec via its Task trailer), contract-check (a contract-surface change without Contract-Change + an updated re-locked contract FAILS and routes back to the architecture gate), and build/test/lint. CI-agnostic bash invoked by GitHub Actions and GitLab CI. Blocking in CI; the human still owns the merge. Never auto-advances.",,{repo: <one of an epic's repos>} {action: wire|run} {base: target branch},3-build,sdlc-implement,,false,demo-repos/<repo>/,checks/*.sh .github/workflows/sdlc-checks.yml .gitlab-ci.yml
+SDLC Workflow,sdlc-pr-template,PR/MR Template,PT,"Build-half Step D: detect a code repo's platform and commit the matching PR/MR template (.github/pull_request_template.md or .gitlab/merge_request_templates/Default.md) with an Impact & Risk block. A high risk level (or a touched contract/auth/payments surface) routes the review to domain owners — the same escalation sdlc-review-gate applies. risk-route.sh prints the required reviewers from a PR body. Never auto-advances.",,{repo: <one of an epic's repos>} {action: wire|route} {body: PR description file},3-build,sdlc-checks,,false,demo-repos/<repo>/,.github/pull_request_template.md .gitlab/merge_request_templates/Default.md checks/risk-route.sh
+SDLC Workflow,sdlc-review-comments,Review Comment Templates,RC,"Install platform-matched PR/MR review-comment scaffolds (committed REVIEW_COMMENTS.md) into a code repo or the product hub, so reviewers leave structured, attributable feedback whose **name (role)** headers map cleanly into the SDLC file ledger. GitHub Saved Replies / GitLab comment templates are per-user, so a committed doc is the repo-level mechanism. Never auto-advances.",,{repo: <one of an epic's repos | hub>} {action: wire},3-build,,,false,<repo>/.github|.gitlab/,REVIEW_COMMENTS.md
+SDLC Workflow,sdlc-hub-bridge,Hub Review Bridge,HB,"The templated PR/MR bridge for the front-half review gate: when the product hub has a platform (.sdlc/hub.json), open a review PR/MR on the hub for an authored artifact, set required reviewers/labels from the routing rule, and provide the read-only gh/glab recipes sdlc-review-gate's sync uses to pull platform comments + approvals into the file ledger. Local-user auth, no stored tokens; file ledger stays the source of truth; degrades to file-only when no platform/CLI. Never auto-advances.",,{epic: EP-<slug>} {artifact: epic.md|architecture.md|ui-design.md|stories/} {action: open|route},1-front,sdlc-review-gate,sdlc-review-gate,false,epics/EP-<slug>/.sdlc/,hub-prs.json
+SDLC Workflow,sdlc-ship,Review & Ship,SH,"Build-half Step E: wire an advisory AI first-pass (CodeRabbit) on the PR, record the human engineer review with the same human_approve discipline as the front gates (owner + 1 reviewer, escalating to domain owners on high risk / contract / auth / payments), and on merge record the ship in epics/<epic>/.sdlc/build-log.json and update the story state. AI review is advisory, never the authority; the human owns the merge. Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {task: T0N} {repo: <repo>} {action: ai-review|approve|ship},3-build,sdlc-pr-template,,false,epics/EP-<slug>/.sdlc/,build-log.json story-status
+SDLC Workflow,sdlc-backfill,Backfill Specs,BF,"Build-half Step G: generate specs for already-built features in an existing repo. Confirm Repomix (npx repomix CLI), pack ONE feature (compress + git logs, secret-scan), feed to AI with a 'describe what exists, do not invent' prompt, write a DRAFT spec marked verified: false. Human approval (reuse sdlc-review-gate) makes it real. Boundary auto-proposed and human-confirmed. A change is blocked only until the features it touches have approved specs. Never auto-advances.",,{repo: <repo>} {feature: <name + globs>} {action: pack|draft|approve|gate},3-build,,,false,demo-repos/<repo>/specs/backfill/<feature>/,spec.md backfill-check.sh
+SDLC Workflow,sdlc-run,Run (Automation),RN,"Phase 4 orchestrator: drive a story's back-half loop (spec→tasks→implement→checks) in one code repo, reading each step's automation dial from build-state — on machine_advance it advances on its own, on human_approve it stops for a human. Records every run in the trust log. Realizes Step B (a clean checks pass auto-advances to the engineer review when earned; any FAIL / scope overrun / contract touch HALTS). set-dial earns/reverts a step's automation (machine_advance gated by the trust threshold; front states and engineer-review refused); kill/unkill toggles the system-wide kill switch. Front states and the human merge gate never auto-advance.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {repo: <repo>} {action: run|set-dial|kill|unkill} {step: <back-step>} {to: human_approve|machine_advance},4-automate,sdlc-spec,sdlc-ship,false,epics/EP-<slug>/.sdlc/,build-state/<story-id>.json trust-log.json
+SDLC Workflow,sdlc-status,SDLC Status,SS,"Read-only: print the full front-state chain, per-step dials, contract lock, story repo tags, and pending approvals at the active gate. For stories in the build half, also print each back-half step's automation dial and status, the trust record (runs / % approved-unchanged / earned vs gathering evidence), and the system-wide kill-switch state.",,{epic: EP-<slug>},1-front,,,false,,

package/skills/sdlc-author-analysis/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: sdlc-author-analysis
+description: 'Optional front state 1 of the gated SDLC. With the analyst, pressure-test a feature idea and write the discovery brief into analysis.md. Assigns the EP-<slug> ID and seeds .sdlc/ state (the 10-step chain that puts analysis before epic). Never auto-advances — hands off to the team review gate. Optional: if skipped, the epic step does this shaping inline. Use when the user says "analyse the idea", "start with analysis", or "author the analysis".'
+---
+
+# SDLC — Author Analysis (optional front state 1)
+
+**Goal:** Produce a human-authored, AI-assisted `analysis.md` — the analyst's discovery brief that
+shapes the feature **before** the epic — assign its stable `EP-<slug>` ID, and initialise the per-epic
+state machine in `.sdlc/`. This is a **front state**: human-authored with AI assist and **never
+auto-advances**. When the analysis is drafted, control passes to `sdlc-review-gate`.
+
+This step is **optional**. When it runs, it is the entry point: it assigns the ID and seeds the
+**10-step** chain (`analysis` before `epic`). When it is **skipped**, `sdlc-author-epic` does the same
+analyst shaping inline and seeds the **8-step** chain — no behaviour change for teams that skip it.
+
+This skill enforces the build plan's core rules: all state lives in files; IDs are generated by the
+engine (never typed by hand); front steps are locked to `human_approve`.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory.
+- Analysis artifacts live under `{project-root}/epics/EP-<slug>/` (build plan §6).
+- Speak in the configured `communication_language`; write documents in `document_output_language`.
+
+## On Activation
+
+### Step 1 — Get the idea
+Ask the user for a one-line feature idea if not provided. If `.sdlc/state.json` already exists for the
+target epic, analysis was already seeded (or the epic is past it) — stop and point the user at
+`sdlc-status`. The entry point seeds state exactly once.
+
+### Step 2 — Shape the idea (assist: analyst)
+Adopt the **analyst** lens (`bmad-agent-analyst`, Mary) to pressure-test the idea in depth: who is the
+user, what problem, what already exists, what options are on the table, what signals success, what is
+out of scope, and what the recommendation to the epic is. This is the discovery the epic will build on.
+
+### Step 2b — Load existing-code context (make the brain code-aware)
+Read the registry `{project-root}/.sdlc/repos.json` (`config.yaml` `code_context`). For **every
+connected repo** (the epic's `repos` are not chosen yet), load the lightweight code-map
+`{project-root}/.sdlc/code-context/<repo>/code-map.md`. Use it so the analysis's **Current state** and
+**Options** reflect what is **already built** — reference existing behaviour rather than re-proposing it.
+
+- **Greenfield-safe:** if `repos.json` is absent or empty, note "no repos connected" and proceed.
+- **Staleness:** if a repo's current HEAD (`git -C <path> rev-parse HEAD`) ≠ its registry `syncedHead`,
+  warn and suggest `sdlc repo refresh <repo>` (a human decision — flag and stop, never auto-refresh);
+  stamp `code-context: stale` in the frontmatter.
+- **Traceability:** record which maps you loaded in the analysis frontmatter `code-context:` field.
+
+### Step 3 — Generate the Epic ID (engine-assigned, never by hand)
+Derive `EP-<slug>` where `slug` is **2–4 lowercase words joined by hyphens**, drawn from the idea
+(e.g. `EP-istifta-inquiries`). Lowercase except the fixed `EP` prefix. **The ID is assigned once and
+never renamed** — renaming breaks every downstream link (build plan §6b). Check
+`{project-root}/epics/` for collisions; if the slug exists, append a distinguishing word.
+
+### Step 4 — Open the authoring branch
+Open the analysis authoring branch `analysis/EP-<slug>` per the shared procedure
+(`references/state-schema.md` → "Authoring branches"): git-safe (skip with a note if `{project-root}`
+is not a git work tree), check out the branch if it exists, else create it from the hub's default
+branch. Author and commit `analysis.md` on it. This is **distinct** from the bridge's `review/…` branch.
+
+### Step 5 — Write the analysis (assist: analyst)
+Write `{project-root}/epics/EP-<slug>/analysis.md` using EXACTLY this template:
+
+```markdown
+---
+id: EP-<slug>
+artifact: analysis
+status: draft
+owner:
+code-context: { repos: [], loaded: <YYYY-MM-DD or none> }   # which code-maps informed this analysis (Step 2b)
+---
+
+## Problem
+<!-- the problem this feature addresses, who feels it -->
+
+## Users / personas
+## Current state (what already exists)
+<!-- code-aware, from the code-maps loaded in Step 2b -->
+
+## Options / opportunities
+## Risks & constraints
+## Success signals
+## Recommendation (hand-off to the epic)
+<!-- the framing the epic should carry forward -->
+```
+
+Fill the body with the user; leave `owner` for the user to set.
+
+### Step 6 — Seed the state machine
+Create `{project-root}/epics/EP-<slug>/.sdlc/state.json` describing the full **10-step** front-state
+sequence (analysis before epic), all steps defaulting to `automation: human_approve`, with every
+authoring step **locked**. Use this exact shape (see `references/state-schema.md`):
+
+```json
+{
+  "epicId": "EP-<slug>",
+  "createdAt": "<YYYY-MM-DD>",
+  "currentStep": "analysis-review",
+  "steps": [
+    { "id": "analysis",           "type": "author",         "artifact": "analysis.md",      "assistance": "review", "automation": "human_approve", "locked": true,  "status": "done",        "risk_tags": [] },
+    { "id": "analysis-review",    "type": "review+approve", "artifact": "analysis.md",      "assistance": "review", "automation": "human_approve", "locked": true,  "status": "in_review",   "risk_tags": [] },
+    { "id": "epic",               "type": "author",         "artifact": "epic.md",          "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
+    { "id": "epic-review",        "type": "review+approve", "artifact": "epic.md",          "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
+    { "id": "architecture",       "type": "author",         "artifact": "architecture.md",  "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
+    { "id": "architecture-review","type": "review+approve", "artifact": "architecture.md",  "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": ["contract"] },
+    { "id": "ui-design",          "type": "author",         "artifact": "ui-design.md",     "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
+    { "id": "ui-design-review",   "type": "review+approve", "artifact": "ui-design.md",     "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
+    { "id": "stories",            "type": "author",         "artifact": "stories/",         "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
+    { "id": "stories-review",     "type": "review+approve", "artifact": "stories/",         "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] }
+  ]
+}
+```
+
+Notes:
+- `analysis-review` carries no `risk_tags` — it is the **base** rule (owner + 1 reviewer).
+- `architecture-review` carries `risk_tags: ["contract"]` so the gate escalates it by default
+  (build plan §4): the contract review needs domain owners, not just owner + 1.
+- Also create an empty approvals ledger `{project-root}/epics/EP-<slug>/.sdlc/approvals.json`
+  and an empty comments ledger `{project-root}/epics/EP-<slug>/.sdlc/comments.json`, each containing
+  `[]`, and the `reviews/` directory.
+
+### Step 7 — Stop at the gate (do NOT advance)
+Report: epic ID, the path to `analysis.md`, and that the next action is **review** via
+`sdlc-review-gate` (base rule: owner + 1 reviewer). **Never mark the analysis-review step approved
+here** — only real reviewers do that through the gate. Front states do not auto-advance. When the
+analysis gate passes, control moves to `sdlc-author-epic`, which reads `analysis.md` as input. When the
+hub has a platform, the gate opens a review PR on the hub (via `sdlc-hub-bridge`) and
+`sdlc-review-gate action: sync` pulls platform approvals/comments into the ledger; otherwise the review
+is recorded file-only.
+
+## Reference
+- State schema, the two chain shapes, and the authoring-branch procedure:
+  `../sdlc-author-epic/references/state-schema.md`.
+- The epic step that consumes this analysis: `../sdlc-author-epic/SKILL.md`.
+- Connecting code repos + the code-context the brain reads: `../sdlc-connect-repos/SKILL.md`.