From afc71eac493a3e3f16421647321b37c6138750ba Mon Sep 17 00:00:00 2001 From: Shay Date: Wed, 17 Jun 2026 07:06:57 -0700 Subject: [PATCH] create docs/grokbuild/README.md - comprehensive SpaceX-level mastery guide for using Grok 4.3 + Grok Build on CORE --- docs/grokbuild/README.md | 177 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 docs/grokbuild/README.md diff --git a/docs/grokbuild/README.md b/docs/grokbuild/README.md new file mode 100644 index 00000000..7f5d174c --- /dev/null +++ b/docs/grokbuild/README.md @@ -0,0 +1,177 @@ +# 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 `feat/grok43-agent-config` (or main once merged). +2. Copy `docs/examples/grok43.env.example` to your local `.env` and fill in your `XAI_API_KEY`. +3. Install Grok Build CLI (if not already): + ```bash + curl -fsSL https://x.ai/cli/install.sh | bash + ``` +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 (Mandatory) +- Invoke `core-bootstrap` skill (or run it manually). +- Read `GROK.md` + `AGENTS.md` + `docs/runtime_contracts.md`. +- Run smoke suite. +- Read 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). + +### Phase 6: Documentation & Handoff +- Write/update the handoff document using `docs/handoff_template.md`. +- Record exact invariants verified, tests run, and open tasks. + +--- + +## 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 +- 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. + +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 Commands + +```bash +# Bootstrap +core-bootstrap + +# Verify core invariant +core test --suite algebra -q + +# Full relevant validation +core test --suite smoke -q && core test --suite cognition -q && core test --suite teaching -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. \ No newline at end of file