core/docs/grokbuild/README.md

Using Grok 4.3 + Grok Build with CORE — Mastery Guide

This document defines the canonical, high-discipline way to use Grok 4.3 and Grok Build on the AssetOverflow/core repository.

The goal is not to make the model "smarter." The goal is to make the engineering process more disciplined, reproducible, and resistant to architectural drift while leveraging powerful agentic tooling.

Grok Build is treated as a bounded engineering laboratory, not an autonomous architecture mutator.

---

1. Philosophy & Mental Model

• Grok 4.3 is fast, high-context, and agentic. This is both its strength and its primary risk on CORE.
• The system must remain coherent by construction. Any change that weakens ||F * reverse(F) - 1||_F < 1e-6, epistemic rigor, or trust boundaries is a defect, not an optimization.
• Human judgment remains the final authority. Grok proposes, sweeps, verifies, and documents. Humans decide.
• Statelessness is a feature, not a bug. We compensate for it structurally (bootstrap skill + handoff docs + prompt library).

Core Principle: Prefer refusal over wrong. Prefer small, verifiable diffs over large ambitious changes.

---

2. Initial Setup (One-Time)

1. Clone the repo and checkout main.
2. Copy docs/examples/grok43.env.example to your local .env and fill in your XAI_API_KEY.
3. Install Grok Build CLI using the current official xAI instructions. Do not pipe installer scripts into a shell unless the source and any available checksum/signature have been verified.
4. Run grok inspect inside the repo root to confirm skills are discovered.
5. (Optional but recommended) Create a personal skills/ override directory if you want local custom skills.

---

3. Standard Session Workflow (Recommended Loop)

Every productive session follows this pattern:

Phase 0: Bootstrap + Workspace Hygiene (Mandatory)

• Invoke /core-bootstrap or run the skill manually through Grok Build.
• Read GROK.md + AGENTS.md + docs/runtime_contracts.md.
• Confirm the current directory and repository root before any operation:

  pwd
  git rev-parse --show-toplevel
  test -f GROK.md
  test -f AGENTS.md
  

• Inspect the local tree before any branch movement:

  git status --short --branch
  git diff --stat
  git diff --name-status
  git diff --cached --name-status
  git stash list
  git worktree list
  

• If the tree is dirty, classify every loose file/change before switching branches:
  • current task work;
  • likely prior PR/branch work;
  • accidental generated artifact;
  • evidence/report file that should be restored;
  • unknown.
• For unknown work, inspect history and open PR state before stashing or restoring:

  git diff -- <path>
  git log --oneline --decorate --all -- <path>
  git branch --sort=-committerdate | head -20
  gh pr list --state open --limit 20
  gh pr status
  

• Preserve unknown work with a descriptive stash; never destroy it blindly:

  git stash push -m "WIP unknown before <task-slug>: <short file summary>" -- <paths>
  

• Establish a clean, current baseline:

  git fetch origin --prune
  git switch main
  git pull --ff-only origin main
  git status --short --branch
  

• For non-trivial implementation, create a fresh worktree from current origin/main:

  git worktree add ../core-<task-slug> origin/main -b <branch-name>
  cd ../core-<task-slug>
  

• Run smoke suite, or record the exact local failure and use repo-native pytest lanes if the core CLI is unavailable.
• Read the most recent relevant HANDOFF-*.md.

Phase 1: Context & Scope

• Paste the Session Entry / Context Load prompt from docs/core-rd-base-prompts.md.
• Clearly state the exact scope and the invariant(s) you will preserve.

Phase 2: Planning (Plan Mode Preferred)

• Use Plan Mode for anything non-trivial.
• Produce a clear plan with:
  • Modules affected
  • Invariants touched
  • Tests/evals that will be impacted
  • Risk assessment

Phase 3: Sweep

• Run full import/call-site/eval sweep before any edit (use pre-edit-sweep skill when available).
• Use the 1M context window aggressively.

Phase 4: Implementation

• Make minimal, load-bearing changes.
• Write failing tests before behavior changes when possible.
• Prefer explicit refusal over silent wrong answers.

Phase 5: Verification

• Run relevant test suites (smallest relevant first).
• Run Versor Coherence Guardian checks on any algebra/field/vault/generate changes.
• Run the Standing Loop Axiom Check (#7 from prompt library).
• Verify PR hygiene before opening:

  git status --short
  git diff --check origin/main...HEAD
  git diff --name-status origin/main...HEAD
  git log --oneline --reverse origin/main..HEAD
  

Phase 6: Documentation, PR Summary & Handoff

• Write/update the handoff document using docs/handoff_template.md.
• Record exact invariants verified, tests run, and open tasks.
• Every PR summary must include:
  • branch name;
  • commit list in order;
  • exact changed files;
  • exact tests/evals run and outputs;
  • whether wrong_total == 0 applies and held;
  • known caveats;
  • explicit non-goals;
  • handoff content or handoff file path.

---

4. Using Grok Build Features at Mastery Level

Plan Mode

• Default for any change touching algebra/, field/, vault/, generate/, teaching/, core/cognition/, or calibration/.
• Use it even for "small" refactors in sensitive areas.
• Review the plan carefully before approval — this is your main defense against drift.

Arena / Parallel Subagents

• Powerful but high-risk if not structured.
• Recommended pattern: Role separation
  • Agent A: ADR / invariant auditor
  • Agent B: Import + call-site sweeper
  • Agent C: Test/eval designer + verifier
  • Agent D: Minimal implementation proposer
  • Agent E: Adversarial reviewer / confuser generator
• All subagent outputs are treated as independent proposals.
• Human (or a final reconciliation agent) merges the reconciled result.
• Every subagent must independently satisfy core invariants before its output is considered.

Skills System

• Prefer skills over ad-hoc prompting for repeated patterns.
• Currently available high-value skills:
  • /core-bootstrap
  • /versor-coherence-guardian
  • /pre-edit-sweep
  • /claim-proposal-guardian
• Use /skillify after successful sessions to capture new reusable workflows.

---

5. Prompt Library (docs/core-rd-base-prompts.md)

This is the canonical set of phase-specific guardrails.

Key sections to use regularly:

• #1 Session Entry / Context Load (start of almost every session)
• #7 Standing Loop Axiom Check (end of every session before commit)
• #8 PR Merge-Readiness Audit (before opening or merging any PR)
• #9 Grok Build Implementation Session (structured session protocol)

The other sections (#2–#6) are used situationally depending on the type of work.

---

6. Anti-Patterns to Avoid

• Treating Grok as the final authority on architecture
• Running large changes without Plan Mode on sensitive modules
• Letting Arena subagents edit without role separation and reconciliation
• Skipping the bootstrap + smoke + handoff loop
• Switching branches before inspecting dirty state
• Deleting, resetting, or restoring unknown local work without classifying it
• Pulling main without first fetching/pruning and verifying fast-forward state
• Reusing stale branches for new tasks that should start from current origin/main
• Using statistical/approximate solutions for exact CGA or epistemic requirements
• Bypassing review gates for claim/pack/policy/identity mutations
• Assuming "it probably didn’t touch the invariant" without verification

---

7. PR & Merge Discipline

Before opening or merging any PR:

1. Run the PR Merge-Readiness Audit prompt (#8).
2. Ensure the diff is minimal and load-bearing.
3. Verify all touched invariants have explicit checks.
4. Confirm relevant tests/evals are green with exact outputs recorded.
5. Write a high-quality handoff document.
6. Include a complete PR summary: branch, commits, changed files, tests/evidence, invariants, caveats, non-goals, and handoff.

For docs/config/agent-governance PRs (like this one), smoke is usually sufficient. For runtime changes, full validation is required.

---

8. Long-Term Maintenance of This Governance Layer

• The files in this setup (GROK.md, AGENTS.md, skills, prompt library, handoff template) are living documents.
• When CORE’s architecture evolves (new invariants, new modules, new boundaries), update the relevant governance files in the same PR or a follow-up.
• Periodically review whether new high-value skills should be extracted from successful sessions.
• Treat this layer with the same rigor as runtime code — it protects the architecture.

---

9. Quick Reference

# Bootstrap (in Grok Build TUI or via skill invocation)
/core-bootstrap

# Confirm root
pwd
git rev-parse --show-toplevel

# Inspect local state before branch movement
git status --short --branch
git diff --stat
git diff --name-status
git diff --cached --name-status
git stash list
git worktree list

# Establish clean current main
git fetch origin --prune
git switch main
git pull --ff-only origin main

# Create fresh worktree for non-trivial work
git worktree add ../core-<task-slug> origin/main -b <branch-name>
cd ../core-<task-slug>

# Verify core invariant
core test --suite algebra -q

# Start Grok Build
grok

# Inspect current skills and config
grok inspect

---

This document, combined with the files it references, represents the current best-known method for using Grok 4.3 + Grok Build on CORE with high discipline and low risk of architectural regression.