@zigrivers/scaffold 2.1.2 → 2.38.0

package/knowledge/core/git-workflow-patterns.md

@@ -0,0 +1,200 @@
+---
+name: git-workflow-patterns
+description: Git branching strategies, commit conventions, PR workflows, merge policies, and CI integration patterns for AI-agent-driven development
+topics: [git, branching, commits, pull-requests, ci-cd, merge-strategy, worktrees]
+---
+
+# Git Workflow Patterns
+
+Structured git workflows for AI-agent-driven projects ensure consistent branching, meaningful commit history, automated quality gates, and smooth multi-agent collaboration via worktrees.
+
+## Summary
+
+### Branching Strategy
+
+The trunk-based development model works best for AI-agent workflows:
+
+- **Main branch** (`main`) — always deployable, protected by CI
+- **Feature branches** — short-lived, created per task or story (`feat/US-xxx-slug`, `fix/bug-description`)
+- **Worktree branches** — parallel agent execution using git worktrees (`agent/<name>/<task>`)
+
+Branch naming conventions:
+```
+feat/US-001-user-registration    # Feature work tied to a story
+fix/login-timeout-handling       # Bug fix
+chore/update-dependencies        # Maintenance
+docs/api-contract-updates        # Documentation only
+```
+
+### Commit Conventions
+
+Use Conventional Commits format for machine-parseable history:
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `ci`
+
+AI agent commits should include the Co-Authored-By trailer for attribution and auditability.
+
+### Pull Request Workflow
+
+Standard PR lifecycle:
+1. Create branch from `main`
+2. Implement changes with passing tests
+3. Push branch, create PR with structured description
+4. CI runs all quality gates (`make check` or equivalent)
+5. Review (automated or manual)
+6. Squash-merge to maintain clean history
+7. Delete branch after merge
+
+## Deep Guidance
+
+### Merge Policies
+
+- **Squash merge** for feature branches — keeps main history clean
+- **Merge commit** for release branches — preserves the merge point
+- **Never force-push** to main or shared branches
+- **Delete branches** after merge to prevent clutter
+
+### CI Integration
+
+Minimum CI pipeline for scaffold projects:
+1. **Lint** — ShellCheck, ESLint, or language-appropriate linter
+2. **Test** — Full test suite including evals
+3. **Build** — Verify compilation/bundling succeeds
+4. **Type check** — For typed languages (TypeScript, etc.)
+
+### Worktree Patterns for Multi-Agent Work
+
+Git worktrees enable parallel agent execution on the same repository:
+
+```bash
+# Create a worktree for an agent
+scripts/setup-agent-worktree.sh agent-name
+
+# Each worktree gets its own branch and working directory
+# Agents can work simultaneously without conflicts
+```
+
+Key rules:
+- Each agent works in its own worktree with its own branch
+- Agents coordinate via the implementation plan task assignments
+- Merge conflicts are resolved by the agent whose branch is behind
+- The main worktree is the coordination point
+
+### Branch Protection Rules
+
+Configure branch protection for `main`:
+- Require status checks to pass before merge
+- Require branches to be up to date before merge
+- Do not allow direct pushes
+- Require squash merging for feature branches
+
+### Commit Message Quality
+
+Good commit messages for AI agents:
+```
+feat(auth): add JWT token refresh endpoint
+
+Implements automatic token refresh when the access token expires
+within 5 minutes. Refresh tokens are rotated on each use.
+
+Closes US-015
+```
+
+Bad commit messages to avoid:
+- `fix stuff` — no context
+- `WIP` — should never be pushed
+- `update` — what was updated?
+
+### PR Description Template
+
+```
+### What changed
+- [1-3 bullet points describing the change]
+
+### Files modified
+- [Specific files/components modified]
+
+### How to test
+- [How to verify the changes work]
+
+### Related
+- [Story ID, issue link, or ADR reference]
+```
+
+### Conflict Resolution Strategy
+
+When multiple agents work in parallel:
+1. Agent finishing first merges normally
+2. Agent finishing second rebases onto updated main
+3. If conflicts arise, the second agent resolves them
+4. Never force-push over another agent's work
+
+Conflict resolution checklist:
+- Pull latest main before starting any task
+- Rebase frequently on long-running branches (every few commits)
+- If a rebase produces conflicts in files you didn't modify, investigate — another agent may have refactored the same area
+- After resolving conflicts, re-run the full test suite before pushing
+- Document unusual conflict resolutions in the commit message body
+
+### Release Workflow
+
+For version-tagged releases:
+1. Ensure all PRs are merged to main
+2. Run full quality gates on main
+3. Create a version tag (`v1.2.3`)
+4. Generate changelog from conventional commits
+5. Push tag to trigger release pipeline
+
+### Semantic Versioning
+
+Follow semver for version tags:
+- **MAJOR** (`X.0.0`) — breaking API changes, incompatible migrations
+- **MINOR** (`0.X.0`) — new features, backward-compatible additions
+- **PATCH** (`0.0.X`) — bug fixes, documentation, internal refactors
+
+Pre-release versions for staging: `v1.2.3-rc.1`, `v1.2.3-beta.1`
+
+### Git Hooks
+
+Pre-commit hooks for quality enforcement:
+```bash
+# .husky/pre-commit or .git/hooks/pre-commit
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Run linter on staged files
+make lint
+
+# Validate frontmatter on changed command files
+./scripts/validate-frontmatter.sh $(git diff --cached --name-only -- 'commands/*.md')
+```
+
+Pre-push hooks for broader validation:
+```bash
+# .husky/pre-push or .git/hooks/pre-push
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Run full test suite before pushing
+make test
+```
+
+### Common Anti-Patterns
+
+Patterns to avoid in AI-agent git workflows:
+
+1. **Long-lived branches** — branches older than 1 day risk merge conflicts. Keep branches short-lived.
+2. **Giant PRs** — PRs with 500+ lines changed are hard to review. Split into smaller, focused PRs.
+3. **Skipping hooks** — `--no-verify` hides real issues. Fix the root cause instead.
+4. **Rebasing shared branches** — only rebase branches that only you use. Shared branches use merge commits.
+5. **Committing generated files** — lock files yes, build output no. Use `.gitignore` aggressively.
+6. **Force-pushing to main** — this is never acceptable. Even if CI is broken, create a fix branch.
+7. **Mixing concerns in one commit** — each commit should be atomic and focused on one change.

package/knowledge/core/multi-model-review-dispatch.md

@@ -0,0 +1,250 @@
+---
+name: multi-model-review-dispatch
+description: Patterns for dispatching reviews to external AI models (Codex, Gemini) at depth 4+, including fallback strategies and finding reconciliation
+topics: [multi-model, code-review, depth-scaling, codex, gemini, review-synthesis]
+---
+
+# Multi-Model Review Dispatch
+
+At higher methodology depths (4+), reviews benefit from independent validation by external AI models. Different models have different blind spots — Codex excels at code-centric analysis while Gemini brings strength in design and architectural reasoning. Dispatching to multiple models and reconciling their findings produces higher-quality reviews than any single model alone. This knowledge covers when to dispatch, how to dispatch, how to handle failures, and how to reconcile disagreements.
+
+## Summary
+
+### When to Dispatch
+
+Multi-model review activates at depth 4+ in the methodology scaling system:
+
+| Depth | Review Approach |
+|-------|----------------|
+| 1-2 | Claude-only, reduced pass count |
+| 3 | Claude-only, full pass count |
+| 4 | Full passes + one external model (if available) |
+| 5 | Full passes + multi-model with reconciliation |
+
+Dispatch is always optional. If no external model CLI is available, the review proceeds as a Claude-only enhanced review with additional self-review passes to partially compensate.
+
+### Model Selection
+
+| Model | Strength | Best For |
+|-------|----------|----------|
+| **Codex** (OpenAI) | Code analysis, implementation correctness, API contract validation | Code reviews, security reviews, API reviews, database schema reviews |
+| **Gemini** (Google) | Design reasoning, architectural patterns, broad context understanding | Architecture reviews, PRD reviews, UX reviews, domain model reviews |
+
+When both models are available at depth 5, dispatch to both and reconcile. At depth 4, choose the model best suited to the artifact type.
+
+### Graceful Fallback
+
+External models are never required. The fallback chain:
+1. Attempt dispatch to selected model(s)
+2. If CLI unavailable → skip that model, note in report
+3. If timeout → use partial results if any, note incompleteness
+4. If all external models fail → Claude-only enhanced review (additional self-review passes)
+
+The review never blocks on external model availability.
+
+## Deep Guidance
+
+### Dispatch Mechanics
+
+#### CLI Availability Check
+
+Before dispatching, verify the model CLI is installed and authenticated:
+
+```bash
+# Codex check
+which codex && codex --version 2>/dev/null
+
+# Gemini check (via Google Cloud CLI or dedicated tool)
+which gemini 2>/dev/null || (which gcloud && gcloud ai models list 2>/dev/null)
+```
+
+If the CLI is not found, skip dispatch immediately. Do not prompt the user to install it — this is a review enhancement, not a requirement.
+
+#### Prompt Formatting
+
+External model prompts must be self-contained. The external model has no access to the pipeline context, CLAUDE.md, or prior conversation. Every dispatch includes:
+
+1. **Artifact content** — The full text of the document being reviewed
+2. **Review focus** — What specific aspects to evaluate (coverage, consistency, correctness)
+3. **Upstream context** — Relevant upstream artifacts that the document should be consistent with
+4. **Output format** — Structured JSON for machine-parseable findings
+
+**Prompt template:**
+```
+You are reviewing the following [artifact type] for a software project.
+
+## Document Under Review
+[full artifact content]
+
+## Upstream Context
+[relevant upstream artifacts, summarized or in full]
+
+## Review Instructions
+Evaluate this document for:
+1. Coverage — Are all expected topics addressed?
+2. Consistency — Does it agree with the upstream context?
+3. Correctness — Are technical claims accurate?
+4. Completeness — Are there gaps that would block downstream work?
+
+## Output Format
+Respond with a JSON array of findings:
+[
+  {
+    "id": "F-001",
+    "severity": "P0|P1|P2|P3",
+    "category": "coverage|consistency|correctness|completeness",
+    "location": "section or line reference",
+    "finding": "description of the issue",
+    "suggestion": "recommended fix"
+  }
+]
+```
+
+#### Output Parsing
+
+External model output is parsed as JSON. Handle common parsing issues:
+- Strip markdown code fences (```json ... ```) if the model wraps output
+- Handle trailing commas in JSON arrays
+- Validate that each finding has the required fields (severity, category, finding)
+- Discard malformed entries rather than failing the entire parse
+
+Store raw output for audit:
+```
+docs/reviews/{artifact}/codex-review.json   — raw Codex findings
+docs/reviews/{artifact}/gemini-review.json  — raw Gemini findings
+docs/reviews/{artifact}/review-summary.md   — reconciled synthesis
+```
+
+### Timeout Handling
+
+External model calls can hang or take unreasonably long. Set reasonable timeouts:
+
+| Operation | Timeout | Rationale |
+|-----------|---------|-----------|
+| CLI availability check | 5 seconds | Should be instant |
+| Small artifact review (<2000 words) | 60 seconds | Quick read and analysis |
+| Medium artifact review (2000-10000 words) | 120 seconds | Needs more processing time |
+| Large artifact review (>10000 words) | 180 seconds | Maximum reasonable wait |
+
+#### Partial Result Handling
+
+If a timeout occurs mid-response:
+1. Check if the partial output contains valid JSON entries
+2. If yes, use the valid entries and note "partial results" in the report
+3. If no, treat as a model failure and fall back
+
+Never wait indefinitely. A review that completes in 3 minutes with Claude-only findings is better than one that blocks for 10 minutes waiting for an external model.
+
+### Finding Reconciliation
+
+When multiple models produce findings, reconciliation synthesizes them into a unified report.
+
+#### Consensus Analysis
+
+Compare findings across models to identify agreement and disagreement:
+
+**Consensus** — Multiple models flag the same issue (possibly with different wording). High confidence in the finding. Use the most specific description.
+
+**Single-source finding** — Only one model flags an issue. Lower confidence but still valuable. Include in the report with a note about which model found it.
+
+**Disagreement** — One model flags an issue that another model explicitly considers correct. Requires manual analysis.
+
+#### Reconciliation Process
+
+1. **Normalize findings.** Map each model's findings to a common schema (severity, category, location, description).
+
+2. **Match findings across models.** Two findings match if they reference the same location and describe the same underlying issue (even with different wording). Use location + category as the matching key.
+
+3. **Score by consensus.**
+   - Found by all models → confidence: high
+   - Found by majority → confidence: medium
+   - Found by one model → confidence: low (but still reported)
+
+4. **Resolve severity disagreements.** When models disagree on severity:
+   - If one says P0 and another says P1 → use P0 (err on the side of caution)
+   - If one says P1 and another says P3 → investigate the specific finding before deciding
+   - Document the disagreement in the synthesis report
+
+5. **Merge descriptions.** When multiple models describe the same finding differently, combine their perspectives. Model A might identify the symptom while Model B identifies the root cause.
+
+#### Disagreement Resolution
+
+When models actively disagree (one flags an issue, another says the same thing is correct):
+
+1. **Read both arguments.** Each model explains its reasoning. One may have a factual error.
+2. **Check against source material.** Read the actual artifact and upstream docs. The correct answer is in the documents, not in model opinions.
+3. **Default to the stricter interpretation.** If genuinely ambiguous, the finding stands at reduced severity (P1 → P2).
+4. **Document the disagreement.** The reconciliation report should note: "Models disagreed on [topic]. Resolution: [decision and rationale]."
+
+### Output Format
+
+#### Review Summary (review-summary.md)
+
+```markdown
+# Multi-Model Review Summary: [Artifact Name]
+
+## Models Used
+- Claude (primary reviewer)
+- Codex (external, depth 4+) — [available/unavailable/timeout]
+- Gemini (external, depth 5) — [available/unavailable/timeout]
+
+## Consensus Findings
+| # | Severity | Finding | Models | Confidence |
+|---|----------|---------|--------|------------|
+| 1 | P0 | [description] | Claude, Codex | High |
+| 2 | P1 | [description] | Claude, Codex, Gemini | High |
+
+## Single-Source Findings
+| # | Severity | Finding | Source | Confidence |
+|---|----------|---------|--------|------------|
+| 3 | P1 | [description] | Gemini | Low |
+
+## Disagreements
+| # | Topic | Claude | Codex | Resolution |
+|---|-------|--------|-------|------------|
+| 4 | [topic] | P1 issue | No issue | [resolution rationale] |
+
+## Reconciliation Notes
+[Any significant observations about model agreement patterns, recurring themes,
+or areas where external models provided unique value]
+```
+
+#### Raw JSON Preservation
+
+Always preserve the raw JSON output from external models, even after reconciliation. The raw findings serve as an audit trail and enable re-analysis if the reconciliation logic is later improved.
+
+```
+docs/reviews/{artifact}/
+  codex-review.json     — raw output from Codex
+  gemini-review.json    — raw output from Gemini
+  review-summary.md     — reconciled synthesis
+```
+
+### Quality Gates
+
+Minimum standards for a multi-model review to be considered complete:
+
+| Gate | Threshold | Rationale |
+|------|-----------|-----------|
+| Minimum finding count | At least 3 findings across all models | A review with zero findings likely missed something |
+| Coverage threshold | Every review pass has at least one finding or explicit "no issues found" note | Ensures all passes were actually executed |
+| Reconciliation completeness | All cross-model disagreements have documented resolutions | No unresolved conflicts |
+| Raw output preserved | JSON files exist for all models that were dispatched | Audit trail |
+
+If the primary Claude review produces zero findings and external models are unavailable, the review should explicitly note this as unusual and recommend a targeted re-review at a later stage.
+
+### Common Anti-Patterns
+
+**Blind trust of external findings.** An external model flags an issue and the reviewer includes it without verification. External models hallucinate — they may flag a "missing section" that actually exists, or cite a "contradiction" based on a misread. Fix: every external finding must be verified against the actual artifact before inclusion in the final report.
+
+**Ignoring disagreements.** Two models disagree, and the reviewer picks one without analysis. Fix: disagreements are the most valuable signal in multi-model review. They identify areas of genuine ambiguity or complexity. Always investigate and document the resolution.
+
+**Dispatching at low depth.** Running external model reviews at depth 1-2 where the review scope is intentionally minimal. The external model does a full analysis anyway, producing findings that are out of scope. Fix: only dispatch at depth 4+. Lower depths use Claude-only review with reduced pass count.
+
+**No fallback plan.** The review pipeline assumes external models are always available. When Codex is down, the review fails entirely. Fix: external dispatch is always optional. The fallback to Claude-only enhanced review must be implemented and tested.
+
+**Over-weighting consensus.** Two models agree on a finding, so it must be correct. But both models may share the same bias (e.g., both flag a pattern as an anti-pattern that is actually appropriate for this project's constraints). Fix: consensus increases confidence but does not guarantee correctness. All findings still require artifact-level verification.
+
+**Dispatching the full pipeline context.** Sending the entire project context (all docs, all code) to the external model. This exceeds context limits and dilutes focus. Fix: send only the artifact under review and the minimal upstream context needed for that specific review.
+
+**Ignoring partial results.** A model times out after producing 3 of 5 findings. The reviewer discards all results because the review is "incomplete." Fix: partial results are still valuable. Include them with a note about incompleteness. Three real findings are better than zero.