Skip to main content

Methodology

What lives here: how we work — principles, processes, decision trees, conventions, the autonomy hierarchy, the discipline that keeps the platform predictable.

Use vs. siblings: Architecture is the structure of the products and systems; methodology is how we work. Templates hold the skeletons; methodology holds the rules for filling them in.

No single template — each methodology doc is its own kind.

This section documents how BeWith builds production software with Claude-based AI assistance. It complements the runtime artifacts:

  • Agents in /agents — the expert agents the AI loads lazily.
  • Skills in /skills — reusable capabilities triggered by keyword.
  • Commands in /commands — slash-invocable workflows.
  • Policies in /policies — the Policy Engine that decides which gates apply.

Status​

This section is being populated. The canonical strategic document is in-tree as ai-engineering-strategy.md (v0.5 — an implementation-annotated adaptation of v0.4). Focused explainers follow.

Pages​

  • ai-engineering-strategy.md — the full architecture (v0.5; annotated where implementation diverges from v0.4).
  • deterministic-ai.md — the eight-principle methodology in one focused page.
  • autonomy-model.md — Hard Floor (7 items) + 6 configurable gates + 8 never-ask, with the four criteria.
  • human-review-in-ai-workflows.md — why human review still matters when the AI writes the code; the convergent/divergent comment distinction and how to disagree with the AI without the disagreement being silently coded away.
  • policy-engine.md — how /policies/*.yaml is evaluated at step 4 of /continue.
  • consumption-model.md — the bewith Claude Code plugin + global core.hooksPath for git hooks + per-repo Copilot pointer; what each install script does (and doesn't).
  • artifact-types.md — the decision tree for choosing between rules, hooks, policies, agents, skills, and commands. Walk this before authoring any new artifact.
  • coding-standards.md — bewith-wide TypeScript invariants (strict equality, lodash isEmpty, ESLint conformity). Read by code-reviewer + every TS-authoring agent.
  • planning-docs.md — conventions for design docs and product specs (filename pattern, body sections).
  • enforcement-tiers.md — the tier ladder for where each rule fires (Tier 0–5), and the criteria for shifting checks left.
  • session-safety.md — write-side isolation (git worktrees) plus read-side freshness (verify memory references against current state). The discipline that keeps concurrent Claude Code sessions from harming each other.
  • state-management.md — design spec for the 3-layer state model + reconciliation algorithm (deferred implementation).
  • glossary.md — curated definitions of the load-bearing terms.