Repository Operating Guide

Model classes and token discipline (Claude Code, Codex and any runner; mandatory)

Name a class here, never a model version. The owner's routing file maps classes to current models (Knowledge Bank, Development, Anthropic Models: model-routing.json; handoff AM-01), so a model upgrade needs no edit in this repository.

• Classes: M Mundane (fastest and cheapest; mechanical work with a clear right answer); N Normal (default; executes an approved plan); X Expert (strongest standard class; plans, judges, hard debugging, final review); S Special occasion (premium class above X; rare; only through the seven-test gate, AM-01 s5, including approved billing). A new model is classified by relative price and vendor positioning (AM-01 s1.1). With no S class available, X is the ceiling.
• Escalate one class, on a trigger only: two failed acceptance checks; an undecidable choice; unreviewed money, tenant, security or legal work. Drop back after the hard step.
• Tokens, both runners: start-up files at most 8,000 tokens and AGENTS.md at most 32 KiB (Codex stops at its byte cap); one task per session, clear or new thread between tasks, compact near 80%; plan to a file, execute in a fresh session (resume a plan from its small RESUME.md only); read the router section then one SKILL.md, search instead of loading; consult only the engine whose domain matches the task; subagents and tools return summaries, cap tool output (tool_output_token_limit), disable unused MCP tools; stable prefix first, no instruction edits mid-session; parallel agents only with a written budget; non-interactive runs for bulk (Batch API only with an approved API budget); effort medium by default, high needs a reason, the maximum needs approval.
• Class S case for this repository (E-08, AM-02): a financial-model and narrative coherence audit before an investor or bank submission; read-only exceptions list. Everything else: X plans, N executes, M for mechanical work.
• Monthly Kaizen, first step: Anthropic currency check (AM-01 s8) and the token-budget lint; record Anthropic currency check YYYY-MM-DD: no change|changed.

Codex-only model setup and Kaizen review

Apply this section only when the active runner is Codex. Claude and other runners must skip it and retain their own models and full engine capabilities.

Before substantive Codex work, resolve this engine's directory and an available Python 3.11+ interpreter (use its absolute path if absent from PATH), then run python <engine-root>/.codex/ensure_model_policy.py --runtime codex --check. If it reports configuration drift, Peter authorises the bounded --runtime codex --apply repair, followed by --check. The helper backs up changes and preserves unrelated settings. If Python or configuration access is unavailable, report the limitation; do not replace the user's config wholesale. Read .codex/model-policy.md for the full contract. Use Luna (gpt-6-luna) with medium reasoning by default for orchestration, research, audit, review, and implementation. Use Astra (gpt-6-astra) only when Peter explicitly selects it for the task; never select or fall back to GPT-5.6. Report unavailable required GPT-6 models. A running session may need restarting for root settings to apply.

Every Kaizen cycle MUST check latest official model releases and actual runtime availability, record dated evidence and a retain/change decision, and evaluate better candidates before recommending replacement. Preserve the pins until Peter authorises a verified change. Missing model-currentness evidence is NOT_ASSESSED. This Codex adapter must not change CLAUDE.md, Claude configuration, domain doctrine, permission settings or skill access.

Universal agent integration

See .skills-engine/engine-manifest.yaml for the declarative contract used by the optional universal coordination package. The router and domain SKILL.md files remain authoritative.

The package may read the router, discover skills, inspect Git, and run only declared checks. Missing evidence is NOT ASSESSED; writes, pulls, publication, submissions, ledger/filing changes, deployment, or control changes require explicit approval.

Project context: if the working project root holds a PROJECT.md with project_schema: 1, read it before planning. It points to this engine's own context sources and never replaces them.

Rules

Always-on cross-cutting principles live in rules/ — see rules/README.md. Load rules/common/core.md alongside the routed skill for any non-trivial task; it is short and does not replace the skill, only sets the baseline the skill operates within.

Mandatory Digital Research currentness gate for Kaizen

Every Kaizen audit, skill edit, reference update, validator change, and standardisation decision MUST begin with the Digital Research Engine. Resolve its location on this device from the global engine-routing table (~/.claude/CLAUDE.md, or AGENTS.md for Codex); never assume a path. Read its source-evaluation and source-verification skills and its currentness gate reference docs/continuous-improvement/kaizen-currentness-gate.md (a path inside that engine, not inside this repository).

Before admitting any standard, policy, law, technology, platform capability, software version, command, security control, benchmark, or lifecycle claim, record source scope, publication/version date, access date, freshness class, review date, support status, and uncertainty. Use current authoritative primary sources; quarantine stale/ambiguous/unsupported claims and mark them NOT_ASSESSED. Books are durable concept inputs only.

Shared agent, command, hook, evidence, and handoff contracts are mapped for this engine in docs/control-plane-adoption.md and governed centrally by docs/engine-control-plane.md in the engineering-catalog engine (resolve it through the global engine-routing table).

Purpose

This repository is a dual-surface skills suite for generating bankable, investor-grade business plans, proposals, pitch materials, and execution frameworks.

The portable unit is the skill directory under skills/:

• skills/<skill-name>/SKILL.md is the canonical shared instruction surface for both Codex and Claude Code
• skills/<skill-name>/references/ stores deeper frameworks, examples, checklists, and long-form material
• AGENTS.md stores repo-wide orchestration, routing, constraints, and verification expectations

Reference sections (read on demand)

These sections were moved verbatim to docs/agents-reference.md. Open the one that applies to the task; do not load the whole file.

• Current Layout (docs/agents-reference.md#current-layout)
• Canonical Authoring Standard (docs/agents-reference.md#canonical-authoring-standard)
• Plan Content Doctrine (docs/agents-reference.md#plan-content-doctrine)

Default Baseline

Kaizen is mandatory across the engine. Load skills/meta-strategy/kaizen-improvement-system/SKILL.md for engine or product audits and book-driven improvement. Publish audits with a hard maximum of 65/100; every remediation plan targets 95/100 and must name evidence, owners, experiments, and re-audit dates. Route current external claims to the Digital Research Engine and finance doctrine to Chwezi.

For serious full business-plan work, start with business-plan-orchestrator, which controls the stage register, cross-engine handoffs, blocker precedence and release bundle. It routes to these baseline skills:

• 00-client-intake
• country-context/{country} where available, otherwise Uganda defaults
• meta-critical-thinking-business-logic
• meta-consulting-synthesis
• meta-bankability-scoring
• meta-due-diligence
• meta-operational-readiness-due-diligence when the plan depends on local banking, tax, licensing, payroll, FX, compliance, logistics, privacy, government interface, or local partnerships

When funding includes equity, convertibles, strategic investors, or blended finance, also load:

• meta-valuation

When execution systems matter, also load:

• meta-monitoring-evaluation
• meta-quarterly-gameplan

When the plan or strategy must explain how the business should digitise, modernise its model, or use technology intelligently beyond a narrow AI section, also load:

• meta-digital-transformation

When a plan includes a website, ecommerce site, content/SEO engine, portal, landing pages, web app, website-design service line, or website startup/recurring costs, also load:

• meta-website-investment-planning

When preparing decks or presentations, also load:

• meta-pitch-preparation
• meta-presentation-design

Before a country or market fact is released, check docs/source-registers/country-market-data.json; an overdue entry or missing claim-level citation blocks the affected conclusion. Before sector assumptions enter operations, risk, implementation or finance, apply references/sector-regulatory-gates.md. Run tools/workbook-audit/formula_map.py and tools/workbook-audit/recalc_check.py on delivered XLSX models (exit 2 from the second means no spreadsheet engine, so the result is not-assessed). Use meta-investment-committee-red-team only after a complete plan, model audit and evidence pack exist.

Before external release of a complete plan, apply references/cross-engine-delivery-contract.md, populate templates/release-evidence-bundle.json, and run tools/release-gate/validate_release_bundle.py. Missing mandatory research, finance, spreadsheet, design, document, security, render, reviewer or authority evidence remains blocking.

Task Routing

• Standalone marketing plan: skills/marketing-sales/marketing-plan-orchestrator/SKILL.md owns market choices, situation analysis, SMART and location-calibrated objectives, positioning, channels (Bullseye), advertising and media, sales plan, economics, budget reconciled to the P&L, KPIs, control and the marketing-plan quality gate. Section 07 remains the business-plan component and follows skills/pipeline/07-marketing-sales-strategy/references/business-plan-marketing-section-standard.md, drawing on the orchestrator's references; social-media-skills is the digital marketing and advertising engine and owns detailed media plans, creative briefs, build specifications, optimisation, attribution, channel execution briefs and content calendars, while this engine owns plan-level advertising objectives, the budget envelope and the media-mix decision reconciled to the P&L (handoff table in the orchestrator's document architecture).
• Strategy rigour: meta-strategic-factor-analysis (EFAS/IFAS/SFAS, TOWS), meta-strategic-audit (read-only audit), meta-strategic-options-evaluation (SAFe, strategy clock, low-cost-rival response, strategy statement gate), meta-business-model-design (score the model before drafting), meta-international-market-entry (cross-border entry), meta-strategic-optionality (exit readiness and sale preparation; valuation to meta-valuation, tax to Chwezi).
• Plan wording: skills/language/writing-quality/references/business-plan-phrase-bank.md and its section, marketing-plan and article files; strategy_type is recorded at 00-client-intake.
• Full bankable plan: business-plan-orchestrator -> 00-client-intake -> evidence design -> meta-business-model-design -> meta-critical-thinking-business-logic -> sections 02 to 16 -> 01-executive-summary -> synthesis/model/challenge gates -> 15-appendices -> 00-plan-assembly -> cross-engine finalisation -> validated release bundle
• Equity or investor plan: baseline plan flow + meta-valuation
• Grant application: 11b-grant-proposal instead of standard funding-request workflow
• Proposal work: proposal-architect plus any relevant sector or funding skills
• Pitch or deck work: meta-pitch-preparation + meta-presentation-design
• Execution planning: meta-monitoring-evaluation + meta-quarterly-gameplan
• Digital-first or technology-modernisation strategy: baseline flow + meta-digital-transformation + 14-ai-integration where AI is materially relevant
• Website, ecommerce, or website-design-service planning: relevant section flow + meta-website-investment-planning + digital-marketing-strategy + meta-premium-go-to-market when premium positioning applies
• EAC e-commerce BDS company diagnostics: use skills/ict/ecommerce-business-model-diagnostic/ when assessing operating e-commerce, marketplace, D2C, B2B, social-commerce, or dropship companies for donor-funded needs assessments, cross-border readiness, and 90-day action planning
• Cross-border e-commerce unit economics: use skills/ict/ecommerce-unit-economics-and-cross-border-margin-model/ before recommending target markets, discounts, paid acquisition, partner channels, or export marketing budgets that depend on margin, CAC, payment, fulfilment, returns, or landed-cost assumptions
• Retail operating-model plans: use skills/industry-guides/retail/guide.md plus skills/industry-guides/retail/references/retail-operating-model-and-engine-plan.md when the plan includes retail, omnichannel commerce, POS-enabled stores, merchandising, pricing, promotions, markdowns, loyalty, fulfilment, returns, shrink, vendor terms, private label, planograms, or retail KPI/WBR cadence
• Pre-ship quality gate (every generated plan, section, deck, narrative, or proposal): run anti-ai-slop last, after writing-quality and meta-critical-thinking-business-logic
• Slop audit cadence: ai-slop-audit runs after each major iteration (each drafted section, completed deck, financial-narrative module, or significant revision), logging a verdict each time; a grade F blocks progression until the blocking findings are fixed. It also auto-runs on request ("audit / review / de-slop this for AI slop", "does this look AI-generated?") and returns a graded A/B/C/F report with a 0–100 genericness score

Core Rules

• Do not call output bankable, investor-grade, or submission-ready unless assumptions, risks, evidence, and financing logic are explicit.
• Do not call output achievable, convincing, or commercially sound unless customer, market, revenue, cost, operating, implementation, and funding logic reconcile.
• For load-bearing claims, make claim, evidence, warrant, assumption, countercase, and implication visible in notes or prose.
• Do not duplicate repo-wide standards across many skills when a baseline skill, shared reference, or this file is the right home.
• Prefer updating an existing overlapping skill over creating a near-duplicate skill.
• Keep SKILL.md concise. Move frameworks, examples, and long teaching content into references/.
• Keep skills declarative, workflow-first, and tool-agnostic.
• Use British English spelling where natural for the repo.
• Any recommendation to digitise, automate, launch a platform, or buy major systems must show customer logic, operating logic, and investment logic - not trend language alone.
• Prefer SMART, context-fit, realistically staged digitisation over all-at-once transformation promises.
• No generated output ships until it passes the anti-ai-slop gate: a specificity floor, verify-before-emit on every stat/market size/citation, an authored strategy, the hard parts covered, and no banned-vocabulary filler. Never invent a TAM, growth rate, or benchmark to fill a section.

Done Means

A high-stakes output is not complete unless:

• the governing thesis is clear
• assumptions are explicit
• load-bearing claims have evidence, warrants, countercases, and implications
• financials reconcile with the narrative
• the funding ask matches the implementation plan
• risks are decision-relevant
• appendices or evidence support the major claims
• the output matches the audience mode: bank, investor, DFI, grant, or strategic partner
• the digital strategy, if included, is commercially justified, operationally realistic, and integrated with the business model rather than bolted on

Anti-AI-Slop Quality Gate

Two skills keep generated output from reading as AI slop. They live at skills/meta-utility/anti-ai-slop/ and skills/meta-utility/ai-slop-audit/.

• anti-ai-slop is MANDATORY and applied in REAL TIME. It is a live constraint applied continuously while generating — to every section, paragraph, slide, and projection as it is written, not only as a final pre-ship pass. The moment a banned word, generic placeholder, unverified market size/figure, or template default appears, fix it in place. Run it on every generated business plan, plan section, executive summary, pitch deck, investment case, funding request, GTM/pricing narrative, financial narrative, grant proposal, or blog post before that output is delivered or called bankable/investor-ready/submission-ready. Apply it after writing-quality and the section skill, and after meta-critical-thinking-business-logic. Financial and market claims must pass its verify-before-emit rule — never invent a market size, growth rate, TAM/SAM/SOM figure, or benchmark.
• ai-slop-audit RUNS AFTER EACH MAJOR ITERATION (not only on request). Run it after each completed unit of work — each drafted plan section, each completed deck, each financial-narrative module, each significant revision, each milestone — logging a verdict each time; a grade F blocks progression to the next section or submission until the blocking findings are fixed. It also auto-runs whenever the user asks to analyse, review, evaluate, critique, audit, score, or de-slop a business plan, pitch deck, financial model or narrative, GTM/pricing narrative, proposal, plan section, or codebase for AI slop, or asks "does this look AI-generated?", and as the final gate before submission. It produces a graded A/B/C/F report with a 0–100 genericness score and a concrete fix per finding.

Verification

Before treating significant skill changes as complete (commands use python3; on Windows use python):

• run python3 -X utf8 scripts/validate_skill_engine.py --baseline docs/quality/skill-quality-baseline.json; it also runs the text-integrity and file-budget checks
• run python3 -X utf8 scripts/routing_smoke_test.py --threshold 1.0 --report --min-precision-at-1 0.80, the floor CI enforces
• run python3 -X utf8 scripts/routing_link_check.py
• validate each changed skill with python3 -X utf8 skills/meta-utility/skill-writing/scripts/quick_validate.py <skill-directory>
• on Peter's development machine, also run the canonical quick validator for every active skill directory. The research engine's scripts/skill_contract_validator.py cannot yet scan this engine by path: run with --root skills on 31 October 2026 it exited 1, read 0 skills and reported six missing_mandatory_resource findings, so its result for this engine is NOT ASSESSED
• keep docs/quality/skill-quality-baseline.json at zero debt; a baseline is never a waiver
• update references when the workflow changes materially
• update evaluation docs if repository capability materially changes
• prefer spot verification of modified skills and routing dependencies
• run the evidence-register, sector-gate, exemplar-pack, release-bundle, workbook and unit-test gates documented in CONTRIBUTING.md when those capabilities are touched; the README's Checks paragraph says which check needs PyYAML, LibreOffice, xlsxwriter or Node.js
• do not weaken scripts/check_text_integrity.py or tests/fixtures/stripped-operator-line-hashes.txt to make an edit pass

Known limits

The shipped SaaS projection workbook is not a lender model: it has no balance sheet and no debt schedule, and its Adjusted EBITDA adds back costs it never deducts (skills/pipeline/10-financial-projections/references/saas-financial-projection-template-3yr-5yr.md, section 0). Do not present its Adjusted EBITDA, net income or closing cash as bankable, and do not quote a DSCR from it. Four evidence-register rows are overdue, so tools/evidence-register/refresh_evidence_register.py --check exits 1 by design; renew a row only from a page you have read, never from a search snippet. The published score, open findings and pending decisions are in docs/kaizen/2026-10-engine-kaizen-pass-2/05-final-report.md and 06-next-cycle.md.

Document and Spreadsheet Tooling

• Before promising .docx, .pdf, .xlsx, financial models, application registers, scoring matrices, budgets, dashboards, or board/investor packs, verify the machine has the required document and spreadsheet tooling.
• Prefer built-in document/spreadsheet plugins where available. Otherwise use local Python libraries such as openpyxl, XlsxWriter, pandas, python-docx, docxtpl, docxcompose, pypandoc, markdown, PyMuPDF, pypdf, pdfplumber, and reportlab.
• Check binaries such as pandoc, LibreOffice/soffice, wkhtmltopdf, and tesseract when conversion or OCR is needed.
• Run a minimal DOCX/XLSX smoke test on a new machine before production export.
• Never claim a Word, PDF, Excel, or model file was generated unless it was actually written and opened or validated.

Migration Guidance

When modernising older skills:

• remove provider-specific command syntax from SKILL.md
• remove chat UI assumptions from SKILL.md
• move duplicated repo-wide rules into AGENTS.md or a shared reference
• add every contract named in the Canonical Authoring Standard; do not fill missing domain decisions, examples, evidence, or acceptance criteria with generic boilerplate

Change Strategy

Use incremental migration, not a repo-wide rewrite:

1. Preserve working skills
2. Upgrade touched skills to the shared structure
3. Add shared references where repetition is high
4. Only reorganise physical directories when the migration cost is justified

Finance & Accounting Trigger

For finance/accounting/IFRS/IAS work, use the Chwezi Accounting Doctrine engine (resolve its location through the global engine-routing table; never hard-code a path) whenever the user's request, the artefact being generated, or the code being edited touches any of:

• Money flows: sales, purchases, payments, refunds, credit notes, expenses
• Stock and inventory
• Payroll
• Tax (VAT, PAYE, WHT, NSSF, income tax, customs, excise, EFRIS, eTIMS)
• Grants, donations, donor restrictions
• Banking, mobile money, POS, card settlement, cash drawer
• Fixed assets
• Financial reports, management accounts, statutory returns
• Chart of Accounts, journals, ledger, posting services, period state, audit trail
• Reconciliation, close, migration, opening balances
• Internal controls, audit, evidence packs
• Any IFRS or IFRS for SMEs section

When the trigger fires:

1. For finance/accounting/IFRS/IAS work, use the Chwezi Accounting Doctrine engine, resolved as above.
2. Read the relevant doctrine reference file in the finance engine (resolved as above).
3. Read the corresponding finance skill SKILL.md in the finance engine (resolved as above).
4. Apply the finance & accounting quality gate from the finance engine (resolved as above).
5. Record the gate run in the artefact manifest.

The finance-module-audit skill (the corresponding skill in the finance engine, resolved as above) auto-runs whenever the user asks to analyse, review, audit, build, propose, or replace any software system with even a slight finance element.

Design / typography / UI/UX (cross-cutting — consult IN ADDITION)

Any work touching how an artifact LOOKS — font/typeface choice, type scale, colour, layout/grid, visual identity, web/desktop/mobile UI screens, or the visual formatting of a DOCX/PPTX/PDF/XLSX — routes to the chwezi-design-engine engine, the single home for ALL design/UI/UX skills and the anti-AI-slop doctrine.

Resolve its location on THIS device from the active runner's global engine-routing table or AGENTS.md — never assume an absolute path; it varies per machine. Then read its README.md → doctrine/design-doctrine.md → glob skills/**/SKILL.md fresh and route by frontmatter (read SKILL.md directly, not via the Skill tool). Content and structure stay in THIS engine; presentation comes from chwezi-design-engine. Hard rule: never use a banned AI-slop font as primary type — hard ban: Inter, Geist, Roboto, Open Sans, Lato, Arial, Fraunces, IBM Plex (all faces); secondary ban: Space Grotesk, Instrument Serif, Instrument Sans, Poppins, Montserrat, Nunito, Nunito Sans, Newsreader, Cormorant (all cuts), Crimson Pro, Plus Jakarta Sans, DM Sans, Outfit, Playfair Display, Lora, Space Mono; Roboto Mono and IBM Plex Mono are banned as monospace choices; Source Sans 3 only as a paired body face; no bare system stacks alone. State the chosen typeface and reason before producing any artifact.

Book extractions and source text

Book extractions, book summaries and raw source text must never be stored in this repository. The former book-extractions/ folder was removed on 2026-09-23 under a zero-loss capability-preservation map. Books are durable concept inputs only: fold their methods into the owning skill's references/ as task-oriented, paraphrased procedures, checklists, templates, phrase patterns and decision rules, cite the source briefly (Author (Year) Title, Publisher), keep verbatim quotation to 25 words or fewer, and route volatile claims through the currentness register or the Digital Research engine. scripts/source_ingestion_guardrail.py fails on any book-extractions/ path.

Human-English editorial standard (2026-08 Kaizen)

Every business plan, pitch, proposal, report, blog post, executive summary, and client-facing message must also load skills/language/writing-quality/references/human-english-five-pass-standard.md. Apply its five passes in real time: reader and purpose, genre and spine, meaning and evidence, sentence/paragraph craft, and proof/read-aloud. Use it alongside skills/language/writing-quality/, skills/language/language-standards/, and skills/meta-utility/anti-ai-slop/; it does not replace financial, market, or reasoning gates.

The standard requires audience-fit British English, concrete nouns, exact verbs, controlled vocabulary, correct grammar and collocation, varied intentional rhythm, visible judgement, and a distinct register for plans, proposals, social copy, web copy, research, political writing, and app messages. Natural writing must never be simulated with errors, slang, fake anecdotes, or unsupported certainty.

DOMAIN PROMPT GENERATION CONTRACT

For a prompt handoff, read the local domain prompt contract. Generate a ready-to-paste prompt using decision, audience, evidence, assumptions, economics, downside case, constraints, output, and acceptance checks. Never prompt around missing market, finance, tax, or legal evidence. Ready-to-paste prompt: include mode, requirements, assumptions, risks, and next action. Failure action: repair the unsupported or unreconciled field, then re-test.

PORTFOLIO CRAFT CONTRACT

Resolve chwezi-engine-agents through the global engine-routing table and load docs/operations/portfolio-craft-standard-2026-09-04.md from it when available. Build plans one decision-bearing section at a time: frame the reader and decision, inspect the evidence and model, draft the smallest useful section, test its assumptions and downside case, revise the argument, and then assemble. Every plan must make its thesis, customer logic, operating logic, financial reconciliation, funding use, counter-case, and next action concrete; delete sections that carry no decision or evidence. Do not produce a full plan as an opaque batch. Apply Observe -> Baseline -> Select -> Experiment -> Check -> Standardise -> Teach -> Re-measure to kaizen itself. Missing source, model, spreadsheet, render, reviewer, or stakeholder evidence is NOT ASSESSED, never a pass.