@hivehub/rulebook 5.7.0 → 5.8.1

package/templates/claude-workflows/bugfix.js

@@ -0,0 +1,94 @@
+export const meta = {
+  name: 'bugfix',
+  description:
+    'Research-first bug fix: root-cause the bug, write a regression test then fix it (TDD), and gate through a quality-gatekeeper verdict (loop max 2). Pass the bug report via args.',
+  phases: [
+    { title: 'Diagnose', model: 'haiku' },
+    { title: 'Fix', model: 'sonnet' },
+    { title: 'Verify', model: 'opus' },
+  ],
+}
+
+const bug =
+  args && typeof args === 'object' && args.bug
+    ? args.bug
+    : typeof args === 'string' && args.trim()
+      ? args
+      : null
+
+if (!bug) {
+  log('No bug description provided. Pass args: { bug: "..." } or a plain string.')
+  return { error: 'missing-bug' }
+}
+
+const VERDICT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['pass', 'regressionTestPresent', 'issues', 'summary'],
+  properties: {
+    pass: { type: 'boolean', description: 'true only if the bug is fixed at the root cause and covered by a passing regression test' },
+    regressionTestPresent: { type: 'boolean' },
+    issues: { type: 'array', items: { type: 'string' } },
+    summary: { type: 'string' },
+  },
+}
+
+phase('Diagnose')
+const diagnosis = await agent(
+  `Root-cause this bug. Research-first: do not guess. Read the relevant code, reproduce mentally, and cite the exact file:line where the defect lives and why it produces the symptom. Read-only.
+Bug report: "${bug}"`,
+  { label: 'diagnose', phase: 'Diagnose', agentType: 'researcher', model: 'haiku' }
+)
+
+const MAX_ROUNDS = 2
+let verdict = null
+let lastIssues = []
+
+for (let round = 1; round <= MAX_ROUNDS; round++) {
+  const fixPrompt =
+    round === 1
+      ? `Fix this bug at its root cause (TDD: write a FAILING regression test that reproduces the bug first, then fix until it passes).
+Bug: "${bug}"
+Root-cause analysis:
+"""
+${diagnosis}
+"""
+Do not mask the symptom — fix the cause. Run type-check + tests before finishing. Report files changed and the regression test added.`
+      : `The quality gatekeeper REJECTED your fix. Address ONLY these issues:
+${lastIssues.map((i, n) => `${n + 1}. ${i}`).join('\n')}
+Re-run type-check + tests. Report what you changed.`
+
+  const fix = await agent(fixPrompt, {
+    label: `fix:round-${round}`,
+    phase: 'Fix',
+    agentType: 'implementer',
+    model: 'sonnet',
+  })
+
+  phase('Verify')
+  verdict = await agent(
+    `Independently verify this bug fix. NO prior context — judge from evidence.
+1. Run \`git --no-pager diff\` to see the change.
+2. Confirm a regression test exists that fails WITHOUT the fix and passes WITH it (run the suite).
+3. Confirm the fix targets the root cause, not the symptom, and introduces no regressions (type-check + full relevant tests).
+Bug: "${bug}"
+Developer report (verify, don't trust): """${fix}"""
+Set pass=true only if the root cause is fixed and covered by a passing regression test.`,
+    { label: `verify:round-${round}`, phase: 'Verify', agentType: 'quality-gatekeeper', model: 'opus', schema: VERDICT_SCHEMA }
+  )
+
+  if (verdict && verdict.pass) {
+    log(`Fix verified on round ${round}.`)
+    break
+  }
+  lastIssues = (verdict && verdict.issues) || ['Gatekeeper returned no verdict']
+  log(`Round ${round} rejected: ${lastIssues.length} issue(s).`)
+}
+
+return {
+  bug,
+  diagnosis,
+  passed: !!(verdict && verdict.pass),
+  issues: verdict && verdict.pass ? [] : lastIssues,
+  verdict: verdict && verdict.summary,
+}

package/templates/claude-workflows/feature-pipeline.js

@@ -0,0 +1,88 @@
+export const meta = {
+  name: 'feature-pipeline',
+  description:
+    'End-to-end feature delivery: research → architect → implement → test → review → document. Sequential because each stage depends on the previous one. Pass the feature description via args.',
+  phases: [
+    { title: 'Research', model: 'haiku' },
+    { title: 'Design', model: 'opus' },
+    { title: 'Implement', model: 'sonnet' },
+    { title: 'Test', model: 'sonnet' },
+    { title: 'Review', model: 'opus' },
+    { title: 'Document', model: 'haiku' },
+  ],
+}
+
+const feature =
+  args && typeof args === 'object' && args.feature
+    ? args.feature
+    : typeof args === 'string' && args.trim()
+      ? args
+      : null
+
+if (!feature) {
+  log('No feature description provided. Pass args: { feature: "..." } or a plain string.')
+  return { error: 'missing-feature' }
+}
+
+const VERDICT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['pass', 'issues', 'summary'],
+  properties: {
+    pass: { type: 'boolean' },
+    issues: { type: 'array', items: { type: 'string' } },
+    summary: { type: 'string' },
+  },
+}
+
+phase('Research')
+const research = await agent(
+  `Research the codebase to inform building this feature: "${feature}".
+Identify the relevant files, existing patterns/conventions, reusable utilities, and risks. Read-only — do not modify anything. Report a concise, actionable map.`,
+  { label: 'research', phase: 'Research', agentType: 'researcher', model: 'haiku' }
+)
+
+phase('Design')
+const design = await agent(
+  `Design the architecture for: "${feature}".
+Use this codebase research as ground truth:
+"""
+${research}
+"""
+Produce a concrete implementation blueprint: files to create/modify, component/data design, and the build sequence. Follow existing conventions; flag trade-offs. Do not write production code yet.`,
+  { label: 'design', phase: 'Design', agentType: 'architect', model: 'opus' }
+)
+
+phase('Implement')
+const impl = await agent(
+  `Implement this feature following the design blueprint below. SDD: trace every behavior to the design; add nothing unspecified. TDD: write tests first where practical.
+Feature: "${feature}"
+Blueprint:
+"""
+${design}
+"""
+Run the type-checker before finishing. Report the files you created/changed.`,
+  { label: 'implement', phase: 'Implement', agentType: 'typescript-implementer', model: 'sonnet' }
+)
+
+phase('Test')
+const tests = await agent(
+  `Write/extend tests for the feature just implemented ("${feature}"). Cover the new behavior and its edge cases with meaningful assertions (no boilerplate). Run \`git --no-pager diff\` to see what was implemented, write the tests, and run them until green. Report coverage of the new code.`,
+  { label: 'test', phase: 'Test', agentType: 'tester', model: 'sonnet' }
+)
+
+phase('Review')
+const review = await agent(
+  `Independently review the full diff for feature "${feature}". Run \`git --no-pager diff\`. Judge correctness, adherence to the design, edge cases, and test adequacy. Run type-check and tests to confirm green. Return pass=true only if it is genuinely ready to merge.
+Implementation report: """${impl}"""
+Test report: """${tests}"""`,
+  { label: 'review', phase: 'Review', agentType: 'code-reviewer', model: 'opus', schema: VERDICT_SCHEMA }
+)
+
+phase('Document')
+const docs = await agent(
+  `Document the feature "${feature}". Run \`git --no-pager diff\` to see what shipped. Update README.md (if user-facing) and add a conventional-commit CHANGELOG.md entry under the unreleased section. English only; document only what exists in the diff.`,
+  { label: 'document', phase: 'Document', agentType: 'docs-writer', model: 'haiku' }
+)
+
+return { feature, design, review, passed: !!(review && review.pass), docs }

package/templates/claude-workflows/release-gate.js

@@ -0,0 +1,64 @@
+export const meta = {
+  name: 'release-gate',
+  description:
+    'Pre-release go/no-go gate. Runs build/type-check, full test suite + coverage, security audit, and docs freshness in parallel, then reports a single go/no-go verdict.',
+  phases: [{ title: 'Checks' }, { title: 'Report' }],
+}
+
+const GATE_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['pass', 'detail'],
+  properties: {
+    pass: { type: 'boolean' },
+    detail: { type: 'string', description: 'concise evidence: command output summary, numbers, or the blocking reason' },
+  },
+}
+
+const GATES = [
+  {
+    key: 'build',
+    agentType: 'build-engineer',
+    model: 'sonnet',
+    prompt:
+      'Run the project type-checker and build (e.g. `npm run type-check` then `npm run build`). pass=true only if both succeed with zero errors. Report the outcome.',
+  },
+  {
+    key: 'tests',
+    agentType: 'tester',
+    model: 'sonnet',
+    prompt:
+      'Run the full test suite with coverage (e.g. `npm run test:coverage`). pass=true only if 100% of tests pass AND coverage meets the project threshold (≥95%). Report pass rate and coverage %.',
+  },
+  {
+    key: 'security',
+    agentType: 'security-reviewer',
+    model: 'haiku',
+    prompt:
+      'Run a production dependency audit (e.g. `npm audit --production`) and scan the diff for committed secrets. pass=true only if there are no high/critical vulnerabilities and no leaked secrets. Report findings.',
+  },
+  {
+    key: 'docs',
+    agentType: 'docs-writer',
+    model: 'haiku',
+    prompt:
+      'Verify release docs are current: CHANGELOG.md has entries for the unreleased changes and README reflects any public API changes. pass=true only if docs are up to date. Report gaps.',
+  },
+]
+
+phase('Checks')
+const results = await parallel(
+  GATES.map((g) => () =>
+    agent(g.prompt, { label: `gate:${g.key}`, phase: 'Checks', agentType: g.agentType, model: g.model, schema: GATE_SCHEMA }).then(
+      (r) => ({ key: g.key, pass: !!(r && r.pass), detail: (r && r.detail) || 'no result' })
+    )
+  )
+)
+
+const gates = results.filter(Boolean)
+const go = gates.length === GATES.length && gates.every((g) => g.pass)
+
+phase('Report')
+log(go ? '✅ GO — all gates passed.' : `⛔ NO-GO — failing: ${gates.filter((g) => !g.pass).map((g) => g.key).join(', ')}`)
+
+return { go, gates }

package/templates/claude-workflows/review-fanout.js

@@ -0,0 +1,125 @@
+export const meta = {
+  name: 'review-fanout',
+  description:
+    'Adversarial multi-dimension review of the current git diff (correctness, security, performance, tests). Each finding is independently verified before it survives, then synthesized into a prioritized report.',
+  phases: [{ title: 'Review' }, { title: 'Verify' }, { title: 'Synthesize', model: 'opus' }],
+}
+
+const FINDINGS_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['findings'],
+  properties: {
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['title', 'file', 'severity', 'detail'],
+        properties: {
+          title: { type: 'string' },
+          file: { type: 'string', description: 'path:line of the issue' },
+          severity: { type: 'string', enum: ['blocker', 'major', 'minor', 'nit'] },
+          detail: { type: 'string', description: 'what is wrong and why it matters' },
+        },
+      },
+    },
+  },
+}
+
+const VERDICT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['real', 'reason'],
+  properties: {
+    real: { type: 'boolean', description: 'true only if the finding is a genuine, reproducible problem' },
+    reason: { type: 'string' },
+  },
+}
+
+const DIMENSIONS = [
+  {
+    key: 'correctness',
+    agentType: 'code-reviewer',
+    model: 'sonnet',
+    focus: 'logic errors, broken edge cases, incorrect error handling, and regressions',
+  },
+  {
+    key: 'security',
+    agentType: 'security-reviewer',
+    model: 'haiku',
+    focus: 'injection, secret leakage, unsafe deserialization, missing authz/validation, vulnerable patterns',
+  },
+  {
+    key: 'performance',
+    agentType: 'performance-engineer',
+    model: 'sonnet',
+    focus: 'N+1 patterns, accidental quadratic work, unnecessary allocations, blocking I/O on hot paths',
+  },
+  {
+    key: 'tests',
+    agentType: 'tester',
+    model: 'sonnet',
+    focus: 'missing test coverage for changed behavior, weak assertions, and untested edge cases',
+  },
+]
+
+// Scoping, in priority order:
+//   args.baseRef — review everything committed since this ref (`git diff <ref>..HEAD`).
+//                  Preferred when the caller commits each unit of work (rulebook-driver).
+//   args.paths   — review only these files in the uncommitted working-tree diff.
+//   (neither)    — review the full uncommitted diff.
+const baseRef = args && typeof args.baseRef === 'string' && args.baseRef ? args.baseRef : null
+const scopePaths = !baseRef && args && Array.isArray(args.paths) && args.paths.length ? args.paths : null
+const diffCmd = baseRef
+  ? `git --no-pager diff ${baseRef}..HEAD`
+  : scopePaths
+    ? `git --no-pager diff -- ${scopePaths.join(' ')} ; git --no-pager diff --staged -- ${scopePaths.join(' ')}`
+    : 'git --no-pager diff ; git --no-pager diff --staged'
+const scopeNote = baseRef
+  ? `Review ONLY the changes committed since ${baseRef} (this task's changeset). Ignore anything before that ref.`
+  : scopePaths
+    ? `Review ONLY these files (the caller's changeset): ${scopePaths.join(', ')}. Ignore changes in any other file.`
+    : 'Review the full current diff.'
+
+// Pipeline: each dimension's findings verify as soon as that dimension finishes —
+// no barrier, so the fast haiku security pass is not blocked by the slower lenses.
+const results = await pipeline(
+  DIMENSIONS,
+  (d) =>
+    agent(
+      `Review the current git diff for ${d.key} issues. Focus on: ${d.focus}.
+${scopeNote}
+Run \`${diffCmd}\` to see the changes. Report only issues introduced or exposed by this diff — not pre-existing debt.`,
+      { label: `review:${d.key}`, phase: 'Review', agentType: d.agentType, model: d.model, schema: FINDINGS_SCHEMA }
+    ),
+  (review, d) =>
+    parallel(
+      (review.findings || []).map((f) => () =>
+        agent(
+          `Adversarially verify this ${d.key} finding. Try to REFUTE it. Read the relevant code at ${f.file}. Default to real=false if you cannot concretely confirm the problem.
+Finding: ${f.title}
+Detail: ${f.detail}`,
+          { label: `verify:${d.key}`, phase: 'Verify', model: 'haiku', schema: VERDICT_SCHEMA }
+        ).then((v) => ({ ...f, dimension: d.key, verdict: v }))
+      )
+    )
+)
+
+const confirmed = results
+  .flat()
+  .filter(Boolean)
+  .filter((f) => f.verdict && f.verdict.real)
+
+// blocking = verified findings severe enough to fail a gate (blocker/major).
+// Consumers (e.g. rulebook-driver) feed these back to the implementer.
+const blocking = confirmed.filter((f) => /^(blocker|major)$/i.test(f.severity || ''))
+
+phase('Synthesize')
+const report = await agent(
+  `Synthesize a prioritized code-review report from these confirmed findings (already verified as real). Group by severity, give each a one-line fix recommendation, and lead with blockers.
+${JSON.stringify(confirmed, null, 2)}`,
+  { label: 'synthesize', phase: 'Synthesize', model: 'opus' }
+)
+
+return { confirmedCount: confirmed.length, confirmed, blocking, report }