@moretea-labs/forge 1.5.0-rc.1

package/assets/project-structures/monorepo.txt

@@ -0,0 +1,63 @@
+# Bun Workspace Monorepo Structure
+
+{{PROJECT_NAME}}/
+├── apps/
+│   ├── web/                      # Astro shell or Vite app surface
+│   │   ├── src/
+│   │   │   ├── routes/
+│   │   │   ├── components/
+│   │   │   └── main.tsx
+│   │   ├── package.json
+│   │   └── vite.config.ts
+│   │
+│   ├── admin/                    # Admin dashboard (optional)
+│   │   ├── app/
+│   │   └── package.json
+│   │
+│   └── mobile/                   # Mobile app (optional)
+│       ├── src/
+│       └── package.json
+│
+├── packages/
+│   ├── ui/                       # Shared UI components
+│   │   ├── src/
+│   │   │   ├── button.tsx
+│   │   │   ├── input.tsx
+│   │   │   └── index.ts
+│   │   ├── package.json
+│   │   └── tsconfig.json
+│   │
+│   ├── utils/                    # Shared utilities
+│   │   ├── src/
+│   │   │   ├── format.ts
+│   │   │   ├── validate.ts
+│   │   │   └── index.ts
+│   │   └── package.json
+│   │
+│   ├── contracts/                # Shared Zod/Valibot contracts
+│   │   ├── src/
+│   │   │   ├── events.ts
+│   │   │   ├── tools.ts
+│   │   │   └── index.ts
+│   │   └── package.json
+│   │
+│   └── tsconfig/                 # Shared TypeScript configs
+│       ├── base.json
+│       ├── react.json
+│       └── package.json
+│
+├── docs/                         # Project documentation
+│   ├── architecture/
+│   │   ├── ARCHITECTURE.md
+│   │   └── tech-stack.md
+│   └── CHANGELOG.md
+├── deploy/                       # Trackable deploy/ops docs, scripts, and SQL
+│   └── sql/                      # Ordered deployment SQL
+├── _ops/                         # Ignored local secrets, env, state, logs
+├── artifacts/                    # Build outputs (not in Git)
+├── turbo.json                    # Optional Turborepo config when scale needs it
+├── package.json                  # Root package.json
+├── bun.lockb                     # Bun lockfile
+├── .gitignore
+├── CLAUDE.md                     # AI development guide
+└── README.md

package/assets/project-structures/remix.txt

@@ -0,0 +1,50 @@
+# Remix Project Structure
+
+{{PROJECT_NAME}}/
+├── app/
+│   ├── routes/                   # Remix routes
+│   │   ├── _index.tsx           # Home (/)
+│   │   ├── admin._index.tsx     # Admin home (/admin)
+│   │   ├── admin.users.tsx      # User list (/admin/users)
+│   │   └── admin.users.$id.tsx  # User detail (/admin/users/:id)
+│   ├── components/
+│   │   ├── ui/                  # shadcn/ui components
+│   │   ├── layout/              # Layout components
+│   │   │   ├── header.tsx
+│   │   │   ├── sidebar.tsx
+│   │   │   └── footer.tsx
+│   │   └── features/            # Business components
+│   ├── lib/
+│   │   ├── supabase.server.ts   # Supabase server client
+│   │   ├── supabase.client.ts   # Supabase browser client
+│   │   ├── utils.ts
+│   │   └── cn.ts
+│   ├── hooks/                   # Custom hooks
+│   ├── stores/                  # Zustand stores
+│   ├── types/
+│   │   └── database.types.ts
+│   ├── utils/
+│   │   ├── auth.server.ts       # Auth utilities
+│   │   └── session.server.ts    # Session management
+│   ├── styles/
+│   │   └── globals.css
+│   ├── root.tsx                 # Root component
+│   └── entry.client.tsx         # Client entry
+├── public/                      # Static assets
+├── docs/                        # Project documentation
+│   ├── architecture/
+│   │   ├── ARCHITECTURE.md
+│   │   └── tech-stack.md
+│   └── CHANGELOG.md
+├── deploy/                      # Trackable deploy/ops docs, scripts, and SQL
+│   └── sql/                     # Ordered deployment SQL
+├── _ops/                        # Ignored local secrets, env, state, logs
+├── artifacts/                   # Build outputs (not in Git)
+├── .env.example
+├── .gitignore
+├── package.json
+├── remix.config.js
+├── tailwind.config.ts
+├── tsconfig.json
+├── CLAUDE.md                    # AI development guide
+└── README.md

package/assets/project-structures/tanstack-start-workers.txt

@@ -0,0 +1,51 @@
+# TanStack Start + Cloudflare Workers Webapp Structure
+
+{{PROJECT_NAME}}/
+├── apps/
+│   └── web/
+│       ├── src/
+│       │   ├── routes/
+│       │   │   ├── __root.tsx          # Root shell with <HeadContent /> and <Scripts />
+│       │   │   ├── index.tsx           # / SSR or prerender-capable public landing
+│       │   │   └── app.tsx             # /app client-only workspace route with ssr: false
+│       │   ├── components/
+│       │   │   ├── landing/            # Public landing sections, meta-friendly content
+│       │   │   └── workspace/          # Authenticated/browser-heavy app components
+│       │   ├── lib/
+│       │   │   ├── api.ts              # VITE_API_BASE_URL / VITE_AGENT_API_URL clients
+│       │   │   └── seo.ts              # title, meta, OG, canonical helpers
+│       │   ├── router.tsx              # createRouter / route tree wiring
+│       │   ├── routeTree.gen.ts        # generated by TanStack Router/Start tooling
+│       │   └── styles.css
+│       ├── public/
+│       ├── vite.config.ts              # cloudflare(), tanstackStart(), react()
+│       ├── wrangler.jsonc              # Worker name, main/assets, compatibility_date
+│       ├── package.json                # build, dev, preview, deploy, cf-typegen
+│       └── tsconfig.json
+├── apps/
+│   ├── api/                            # optional Hono Worker only when API owns data authority
+│   ├── agent/                          # optional Agent Worker only when agent runtime is separate
+│   └── mcp/                            # optional MCP Worker only when external tool access exists
+├── packages/
+│   └── contracts/                      # shared Zod/Valibot route, API, agent, and UI contracts
+├── deploy/
+│   ├── env/.env.example                # VITE_API_BASE_URL, VITE_AGENT_API_URL, public site URL
+│   └── runbooks/                       # domain cutover, Worker routes, rollback notes
+└── docs/
+    └── architecture/                   # web SSR/client boundary and backend runtime ownership
+
+Route boundary:
+- `/`: public landing route. It must return crawler-visible HTML, title/meta,
+  Open Graph tags, and canonical URL from the Worker SSR/prerender path.
+- `/app`: workspace route. Set route-level `ssr: false` or an equivalent
+  client-only boundary; do not SSR tenant workspace data.
+- Browser-only or WebGL components should be `React.lazy`/client-only imports
+  inside `/app`, not top-level imports in server-rendered route modules.
+
+Deployment boundary:
+- Deploy `apps/web` as one Cloudflare Worker with Worker assets and
+  `wrangler deploy`; do not scaffold a second default frontend component.
+- Keep backend Workers separate only when they own API, Agent, MCP, queue, or
+  storage authority.
+- Keep any legacy `apps/marketing` Pages surface as explicit rollback material,
+  not as the default scaffold target.

package/assets/project-structures/vite-tanstack.txt

@@ -0,0 +1,58 @@
+# Vite + TanStack Router Client-Only Project Structure
+
+Use this structure for dense interactive apps, dashboards, internal tools, and
+client-only product surfaces. It does not provide crawler-visible SSR landing
+HTML. If the same webapp needs public SEO/SSR at `/` plus an authenticated or
+browser-heavy workspace under `/app`, choose the TanStack Start + Cloudflare
+Workers model instead of scaffolding separate `apps/marketing` and `apps/web`
+frontend deployments.
+
+{{PROJECT_NAME}}/
+├── src/
+│   ├── routes/                  # TanStack Router routes
+│   │   ├── __root.tsx          # Root route
+│   │   ├── index.tsx           # Home page (/)
+│   │   ├── _auth/              # Auth layout
+│   │   │   ├── login.tsx       # /login
+│   │   │   └── register.tsx    # /register
+│   │   └── _app/               # Main app layout
+│   │       ├── dashboard.tsx   # /dashboard
+│   │       └── users/
+│   │           ├── index.tsx   # /users
+│   │           └── $id.tsx     # /users/:id
+│   ├── components/
+│   │   ├── ui/                 # shadcn/ui components
+│   │   ├── layout/             # Layout components
+│   │   │   ├── header.tsx
+│   │   │   ├── sidebar.tsx
+│   │   │   └── footer.tsx
+│   │   └── features/           # Business components
+│   ├── lib/
+│   │   ├── supabase.ts         # Supabase client
+│   │   ├── utils.ts            # Utilities
+│   │   └── cn.ts               # className merge
+│   ├── hooks/                  # Custom hooks
+│   ├── stores/                 # Zustand stores
+│   ├── types/                  # TypeScript types
+│   │   └── database.types.ts   # Supabase generated types
+│   ├── styles/
+│   │   └── globals.css
+│   └── main.tsx                # Entry point
+├── public/                     # Static assets
+├── docs/                       # Project documentation
+│   ├── architecture/
+│   │   ├── ARCHITECTURE.md
+│   │   └── tech-stack.md
+│   └── CHANGELOG.md
+├── deploy/                     # Trackable deploy/ops docs, scripts, and SQL
+│   └── sql/                    # Ordered deployment SQL
+├── _ops/                       # Ignored local secrets, env, state, logs
+├── artifacts/                  # Build outputs (not in Git)
+├── .env.example
+├── .gitignore
+├── package.json
+├── vite.config.ts
+├── tailwind.config.ts
+├── tsconfig.json
+├── CLAUDE.md                   # AI development guide
+└── README.md

package/assets/reference-configs/AGENTS.md

@@ -0,0 +1,13 @@
+# Functional Block Agent Context
+
+Keep this file focused on the local contract for this primary functional block.
+
+## Local Context Contract
+
+- Describe only the ownership, boundaries, stable entrypoints, and local verification commands for this functional block.
+- Keep sibling `CLAUDE.md` and `AGENTS.md` files aligned. Claude Code consumes `CLAUDE.md`; Codex consumes `AGENTS.md`.
+- Record the local LSP/tooling profile here when it differs from the repo default.
+- Route deep implementation detail into nearby docs instead of inflating root agent context files.
+- Treat `.ai/context/context-map.json` as the index of discoverable context files.
+- Do not keep pushing context files deeper by default; add lower-level files only for a separately owned functional block with its own commands and invariants.
+- Prefer repo-local workflow artifacts over tool-specific chat memory.

package/assets/reference-configs/CLAUDE.md

@@ -0,0 +1,13 @@
+# Functional Block Agent Context
+
+Keep this file focused on the local contract for this primary functional block.
+
+## Local Context Contract
+
+- Describe only the ownership, boundaries, stable entrypoints, and local verification commands for this functional block.
+- Keep sibling `CLAUDE.md` and `AGENTS.md` files aligned. Claude Code consumes `CLAUDE.md`; Codex consumes `AGENTS.md`.
+- Record the local LSP/tooling profile here when it differs from the repo default.
+- Route deep implementation detail into nearby docs instead of inflating root agent context files.
+- Treat `.ai/context/context-map.json` as the index of discoverable context files.
+- Do not keep pushing context files deeper by default; add lower-level files only for a separately owned functional block with its own commands and invariants.
+- Prefer repo-local workflow artifacts over tool-specific chat memory.

package/assets/reference-configs/agentic-development-flow.md

@@ -0,0 +1,94 @@
+# Agentic Development Flow
+
+Use this reference when choosing the daily agentic development mode. Keep the
+root prompt concise; this file owns the detailed routing.
+
+## Skill Routing
+
+| Work type | Default route | Output |
+|-----------|---------------|--------|
+| Product discovery, demand reality, "is this worth building" | gstack `office-hours` | Product direction or design doc before engineering planning |
+| Complex engineering plan, architecture lock-in, cross-module refactor | gstack `plan-eng-review` | Approved execution plan with architecture, data flow, edge cases, and tests |
+| UI/UX or design-system plan | gstack `plan-design-review` | Design critique and plan fixes before implementation |
+| Small or medium feature/fix plan | Waza `/think` | Concise approved plan, then implementation on request |
+| Bug, regression, error, crash, failing test | Waza `/hunt` | Root cause sentence with evidence before any fix |
+| Implemented diff, pre-merge, release follow-through | Waza `/check` | Review findings, safe fixes, verification, and shipment state |
+| Architecture diagram or system-flow diagram | Markdown Mermaid first, `mermaid` for human HTML | Semantic Mermaid in architecture docs plus optional rendered HTML grounded in repo context |
+
+## forge Command Surface
+
+Use these CLI-backed command facades when the work is about installing,
+migrating, repairing, or verifying this repo-local harness:
+
+| Work type | Command | Boundary |
+|-----------|---------|----------|
+| Decision-complete harness plan | `forge-plan` | Plans only; no repo mutation by default |
+| Review an existing harness plan | `forge-review` | Product, engineering, design, and DevEx review dimensions |
+| Automatic workflow pipeline | `forge-autoplan` | Plan -> two self-review passes -> implementation -> `/check` -> `forge-ship` |
+| Ship finished work | `forge-ship` | Validates finished worktrees, pushes branches, and creates PRs by default |
+| Add harness to an existing repo | `forge-init` | Uses inspector and migration engine; does not create an app stack |
+| Create a new app or module scaffold | `forge-scaffold` | Uses plan catalog A-K, then attaches the harness |
+| Convert legacy workflow surfaces | `forge-migrate` | Archives or preserves user-authored legacy docs |
+| Refresh an installed harness | `forge-upgrade` | Runs manifest-owned upgrade actions only |
+| Add selected capability boundaries | `forge-capability` | Updates capability registry and local contracts without full init/migrate/upgrade |
+| Resolve architecture docs or diagrams | `forge-architecture` | Handles architecture drift requests without full harness refresh |
+| Prepare or resume handoff | `forge-handoff` | Refreshes Codex handoff packets without running full checks |
+| Check deploy and ops config | `forge-deploy` | Read-only deploy/_ops readiness check without publishing |
+| Fix broken current harness behavior | `forge-repair` | Task sync, hook routing, handoff, context, policy, or helper drift |
+| Verify readiness | `forge-check` | Workflow gates, task sync, inspector, migration dry-run, and readiness yellow flags |
+| Generate an upper-layer PRD | `forge-prd` | `$geju` direction pass, Claude-first `claude -p --model opus` drafting, Codex fallback only when needed, PRD in `plans/prds/*.prd.md` |
+| Plan and run a program-level sprint | `forge-sprint` | Upper-layer PRD in `plans/prds/`, sprint backlog in `plans/sprints/`; each row expands through `$think` before plan -> contract -> worktree |
+| Prepare a bounded native goal session | `forge-goal` / `forge:goal` | Codex/Claude `/goal` prompt from detailed PRD or Sprint artifacts; stops to request those documents when missing |
+| Configure GPT Pro local bridge | `forge-gptpro-setup` / `forge:gptpro_setup` | Separates `gptpro_browser` local ChatGPT Web browser/session consults from `gptpro_mcp` ChatGPT Connector MCP sidecar setup; preserves auth, tunnel, and API-billing boundaries |
+| Consult GPT Pro through browser session | `forge-gptpro` / `forge:gptpro` | Uses `gptpro consult/read/continue/open` wording while mapping to `browser-consult`, `browser-session`, `browser-followup`, and `browser-open` engine commands |
+
+`hooks-init`, `docs-init`, and `create-project-dirs` are not public commands.
+They are implementation steps behind `init`, `scaffold`, `migrate`, and
+`upgrade`.
+
+## Due Diligence Levels
+
+P1/P2/P3 is the shared due-diligence protocol underneath the routing.
+
+- `P1_GLOBAL_ARCHITECTURE`: identify real boundaries, entrypoints, owners, authoritative files, dependencies, and out-of-scope areas.
+- `P2_DATA_FLOW_TRACE`: walk one concrete route through requests, UI events, jobs, config, messages, or database values to the final output.
+- `P3_DESIGN_DECISION`: explain why the current shape exists, which invariant must stay true, and why the chosen change is the smallest coherent one.
+
+For small tasks, keep P1/P2/P3 internal and report only the result. For
+`plan-eng-review`, `/hunt`, risky refactors, deployments, auth/payment/data
+work, or shared contracts, report the P1/P2/P3 evidence explicitly.
+
+## Daily Flow
+
+| Agent reads first | Human reviews first |
+|-----------|---------|
+| Current user prompt and referenced files | Human Review Card in `tasks/reviews/<task>.review.md` |
+| `AGENTS.md` / `CLAUDE.md` and active plan | Changed files and active contract scope |
+| Active contract, notes, latest checks, and handoff | Latest trace/checks, residual risk, rollback |
+| `tasks/current.md` only for orientation | External acceptance or manual override |
+
+1. Route the request by intent before reading broadly.
+2. Read the repo-local contract first: `AGENTS.md` or `CLAUDE.md`, `tasks/todos.md`, `tasks/lessons.md`, and `.ai/harness/policy.json`.
+3. Use the selected skill or mode to produce either an approved plan, a root cause, or a review verdict.
+4. When Codex Plan mode, Waza `/think`, or `forge-plan` produces a decision-complete plan, capture it into `plans/` with `.ai/harness/scripts/capture-plan.sh --slug <slug> --title <title>` and the plan text on stdin.
+5. Approved plans must include `## Evidence Contract` with state/progress path, verification evidence, evaluator rubric, stop condition, and rollback surface before execution. `capture-plan.sh` supplies this contract for captured planning output.
+6. Convert approved plans to execution scaffolding with `.ai/harness/scripts/plan-to-todo.sh --plan <plan>`; if approval is already explicit, use `.ai/harness/scripts/capture-plan.sh --status Approved --execute ...`. The plan's own `## Task Breakdown` remains the execution checklist; `tasks/todos.md` remains a deferred-goal ledger. Contract-level plans are projected into a linked `codex/<slug>` worktree when the policy enables it.
+7. For Sprint execution, treat each row in `plans/sprints/*.sprint.md` as a long-task waypoint. Use `$think` to expand the row into a decision-complete `plans/plan-*.md` before coding; do not treat the sprint row itself as an implementation plan.
+8. Use `.ai/harness/scripts/refresh-current-status.sh` for an explicit `tasks/current.md` preview or `--write` snapshot. In non-target worktrees, `git show <target>:tasks/current.md` reads the mainline snapshot, but it never replaces source artifacts.
+9. After substantive changes, run project checks and record evidence in `tasks/`. For contract worktrees, run Waza `/check`, start host-aware external acceptance in parallel, fill the review artifact from both verdicts, then use `forge-ship` for default PR closeout. It calls `.ai/harness/scripts/contract-worktree.sh finish --no-merge`, pushes the `codex/<slug>` branch, and opens a draft PR. Use `forge-ship --local-merge` only when an explicit maintainer workflow wants the older fast-forward merge and cleanup path.
+
+## Passive Plan Capture
+
+- Codex Plan mode and Waza `/think` do not need the user to remember `new-sprint` or `plan-to-todo`.
+- The agent should capture decision-complete planning output with `.ai/harness/scripts/capture-plan.sh`; the script sets `.ai/harness/active-plan`, writes `.ai/harness/active-worktree`, mirrors `.claude/.active-plan`, and writes a timestamped `plans/plan-*.md` artifact.
+- Planning capture is allowed before implementation. Contract, review, notes, and worktree artifacts are generated only after explicit implementation approval; `tasks/todos.md` is not a duplicate of plan tasks.
+- Current-status capture is separate from planning capture: `tasks/current.md` is regenerated from artifacts for orientation, not edited as a plan or task list.
+
+## Boundaries
+
+- Do not route large architecture decisions through Waza `/think` by default.
+- Do not use gstack plan review for routine local edits where `/think` or direct execution is enough.
+- Hooks may emit advisory Waza `/check` and `/health` route hints on prompt submit. Review/release prompts emit a host-aware `[ExternalAcceptance]` prompt telling the main agent to run the peer reviewer in parallel and paste `## External Acceptance Advice` into the review file; done/finish gates block only on that recorded evidence. Hooks must not mutate files or auto-run peer CLIs based on semantic intent. `[CrossReview]` remains a lightweight debug/spec/test advisory. Plan capture is an agent action after a planning mode produces a concrete plan.
+- Keep `office-hours` for product-demand shaping; use `plan-eng-review` when engineering execution needs to be locked.
+- Treat subagent and parallel-agent execution as a main-agent decision based on task breadth, context impact, raw-log volume, and callable tools. Do not ask the user for spawn confirmation; if no runner is callable or spawning is not worth the context cost, complete the same P1/P2/P3 trace in the main thread and persist evidence-backed conclusions in `docs/researches/`.
+- Do not turn `tasks/current.md` into a hand-written kanban or memo. Use plans, workstreams, notes, reviews, checks, and handoff files as the authoritative surfaces.

package/assets/reference-configs/ai-workflows.md

@@ -0,0 +1,14 @@
+# AI-Assisted Development Workflows Reference
+
+> Externalized: full reference lives in default brain.
+
+## Default Brain
+
+- File vault: `brain/forge/references/ai-assisted-workflows-reference.md`
+- gbrain slug: `references/ai-assisted-workflows-reference`
+
+## Repo Role
+
+This repo keeps only this pointer so generated projects do not carry a long
+generic workflow catalog by default. Runtime workflow routing remains in
+`docs/reference-configs/agentic-development-flow.md` and `.ai/harness/policy.json`.

package/assets/reference-configs/changelog-versioning.md

@@ -0,0 +1,13 @@
+# Changelog & Versioning Reference
+
+> Externalized: full reference lives in default brain.
+
+## Default Brain
+
+- File vault: `brain/forge/references/changelog-versioning-reference.md`
+- gbrain slug: `references/changelog-versioning-reference`
+
+## Repo Role
+
+The actual release history stays in `docs/CHANGELOG.md`. General changelog and
+versioning practice belongs in the external reference.

package/assets/reference-configs/coding-standards.md

@@ -0,0 +1,14 @@
+# Coding Standards Reference
+
+> Externalized: full reference lives in default brain.
+
+## Default Brain
+
+- File vault: `brain/forge/references/coding-standards-reference.md`
+- gbrain slug: `references/coding-standards-reference`
+
+## Repo Role
+
+Project-specific coding constraints stay in root agent files, workflow policy,
+tests, and task contracts. General coding standards belong in the external
+reference.

package/assets/reference-configs/development-protocol.md

@@ -0,0 +1,21 @@
+# Development Protocol Reference
+
+> Partially externalized: full pattern lives in default brain.
+
+## Default Brain
+
+- File vault: `brain/forge/patterns/pattern-agentic-development-protocol.md`
+- gbrain slug: `patterns/pattern-agentic-development-protocol`
+
+## Repo Role
+
+The executable source of truth is still repo-local:
+
+- Active execution: `plans/plan-*.md` `## Task Breakdown` plus `tasks/contracts/`
+- Deferred goals: `tasks/todos.md`
+- Plans: `plans/`
+- Contracts: `tasks/contracts/`
+- Reviews: `tasks/reviews/`
+- Hook ownership and parity: `docs/reference-configs/hook-operations.md`
+
+Use the external pattern for broader feature, bug, and response-shaping guidance.

package/assets/reference-configs/document-generation.md

@@ -0,0 +1,38 @@
+# Document Generation
+
+Generated repos use a minimal documentation profile by default.
+
+## Required
+
+- `docs/spec.md`: stable product or operator outcome.
+- `docs/architecture/index.md`: umbrella architecture ledger, pending drift requests, snapshots, and diagram links.
+- `tasks/`: execution, lessons, research, contracts, and reviews.
+- `tasks/workstreams/`: durable capability workstream ledgers; `tasks/todos.md` is only the deferred-goal ledger.
+- `.ai/harness/`: workflow policy, checks, handoff, failures, and run state.
+
+## On Demand
+
+Create these only when the agent has concrete repo evidence or the user asks:
+
+- `docs/brief.md`: product positioning and user scope.
+- `docs/tech-stack.md`: confirmed runtime, framework, and dependency choices.
+- `docs/decisions.md`: accepted architecture decisions with trade-offs.
+- `docs/architecture/snapshots/*.md`: current module boundaries and data flow for architecture-sensitive changes.
+- Mermaid fenced blocks in `docs/architecture/modules/**.md` or `docs/architecture/snapshots/*.md`: semantic diagram source for agents and review diffs.
+- `docs/architecture/diagrams/*.html`: optional human-readable `mermaid` renderings produced when a visual is clearer than prose.
+- `docs/packages.md`: package inventory for real multi-package repos.
+- `plans/prds/*.prd.md`: upper-layer PRDs generated through `forge-prd` from `.claude/templates/prd.template.md`; keep Sprint backlogs in `plans/sprints/`.
+
+## Rules
+
+- Do not create empty business docs as placeholders.
+- Do not create root `specs/`; use `docs/spec.md` for stable product intent, `interfaces/` for machine-consumed runtime boundaries, and tests for executable behavior.
+- Do not duplicate workflow rules already indexed in `docs/reference-configs/`.
+- Prefer short docs that name sources, owners, and verification commands.
+- Let capability `CLAUDE.md` and `AGENTS.md` carry local contract projections; root docs stay concise.
+- Keep complete workstream TODOs in `tasks/workstreams/<domain>/<capability>/`; contract blocks should link to them instead of becoming task logs.
+- Keep onboarding docs split by reader: agents read active source artifacts first; humans review the Human Review Card, diff, latest trace, and rollback first.
+- Hooks may create `docs/architecture/requests/*.md`; agents own semantic snapshots, embedded Mermaid, and optional `mermaid` HTML output.
+- Archive handled architecture requests with `.ai/harness/scripts/archive-architecture-request.sh`; keep `docs/architecture/requests/` pending-only and preserve handled requests under `docs/architecture/requests/archive/YYYY/`.
+- When both Mermaid and HTML exist, keep the Mermaid in Markdown as the semantic source and make the HTML link back to that Markdown source.
+- Treat `mermaid` as an external installed skill dependency at `~/.codex/skills/mermaid`; do not copy or inline its assets into generated repos.

package/assets/reference-configs/evaluator-rubric.md

@@ -0,0 +1,19 @@
+# Evaluator Rubric
+
+> Partially externalized: full rubric lives in default brain.
+
+## Default Brain
+
+- File vault: `brain/forge/references/evaluator-rubric-reference.md`
+- gbrain slug: `references/evaluator-rubric-reference`
+
+## Repo Role
+
+Keep pass/fail evidence in `tasks/reviews/<plan-stem>.review.md` and
+`.ai/harness/checks/latest.json`. Use the external rubric for detailed scoring
+dimensions and review examples.
+
+## Hard Threshold
+
+Do not mark a sprint complete unless the review artifact has fresh evidence and
+the active contract verification passes.