@moretea-labs/forge 1.5.0-rc.1

package/assets/initializer-question-pack.v4.schema.json

@@ -0,0 +1,169 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "initializer-question-pack.v4.schema.json",
+  "type": "object",
+  "required": [
+    "version",
+    "goal",
+    "decisionPoints",
+    "planTiers",
+    "inferredDefaults",
+    "runtimeProfiles",
+    "orchestrationProfiles",
+    "evaluationProfiles",
+    "handoffProfiles",
+    "recoveryProfiles",
+    "stateProfiles",
+    "contextProfiles",
+    "webappRenderingModels",
+    "aiNativeProfiles"
+  ],
+  "properties": {
+    "version": {
+      "const": "initializer-question-pack.v4"
+    },
+    "goal": {
+      "type": "string"
+    },
+    "decisionPoints": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "batch", "questions", "required"],
+        "properties": {
+          "id": { "type": "string" },
+          "title": { "type": "string" },
+          "batch": { "type": "integer", "minimum": 1 },
+          "questions": { "type": "array", "items": { "type": "string" } },
+          "required": { "type": "boolean" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "planTiers": {
+      "type": "object",
+      "required": ["core", "presets"],
+      "properties": {
+        "core": { "type": "array", "items": { "type": "string" } },
+        "presets": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "inferredDefaults": {
+      "type": "object",
+      "required": [
+        "packageManagerPriority",
+        "runtimeProfile",
+        "orchestrationProfile",
+        "evaluationProfile",
+        "handoffProfile",
+        "recoveryProfile",
+        "stateProfile",
+        "contextProfile",
+        "aiNativeProfile",
+        "webappRenderingModel"
+      ],
+      "properties": {
+        "packageManagerPriority": { "type": "array", "items": { "type": "string" } },
+        "runtimeProfile": { "type": "string" },
+        "orchestrationProfile": { "type": "string" },
+        "evaluationProfile": { "type": "string" },
+        "handoffProfile": { "type": "string" },
+        "recoveryProfile": { "type": "string" },
+        "stateProfile": { "type": "string" },
+        "contextProfile": { "type": "string" },
+        "documentationProfile": { "type": "string" },
+        "aiNativeProfile": { "type": "string" },
+        "webappRenderingModel": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "runtimeProfiles": {
+      "type": "object"
+    },
+    "orchestrationProfiles": {
+      "type": "object"
+    },
+    "evaluationProfiles": {
+      "type": "object"
+    },
+    "handoffProfiles": {
+      "type": "object"
+    },
+    "recoveryProfiles": {
+      "type": "object"
+    },
+    "stateProfiles": {
+      "type": "object"
+    },
+    "contextProfiles": {
+      "type": "object"
+    },
+    "webappRenderingModels": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "object",
+        "required": [
+          "label",
+          "description",
+          "frontend",
+          "deployment",
+          "publicRoute",
+          "appRoute",
+          "fallback"
+        ],
+        "properties": {
+          "label": { "type": "string" },
+          "description": { "type": "string" },
+          "frontend": { "type": "string" },
+          "deployment": { "type": "string" },
+          "publicRoute": { "type": "string" },
+          "appRoute": { "type": "string" },
+          "fallback": { "type": "string" },
+          "projectStructureFile": { "type": "string" },
+          "techStackRows": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "aiNativeProfiles": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "object",
+        "required": [
+          "label",
+          "description",
+          "frontend",
+          "runtimeProtocol",
+          "backend",
+          "stateDefault",
+          "sidecarPolicy",
+          "uiSchema"
+        ],
+        "properties": {
+          "label": { "type": "string" },
+          "description": { "type": "string" },
+          "frontend": { "type": "string" },
+          "runtimeProtocol": { "type": "string" },
+          "backend": { "type": "string" },
+          "stateDefault": { "type": "string" },
+          "sidecarPolicy": { "type": "string" },
+          "uiSchema": { "type": "string" },
+          "projectStructureFile": { "type": "string" },
+          "techStackRows": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/assets/partials/01-header.partial.md

@@ -0,0 +1,10 @@
+# {{PROJECT_NAME}} Development Guide
+
+> **Developer**: {{USER_NAME}}
+> **Service Target**: {{SERVICE_TARGET}}
+> **Interaction Style**: {{INTERACTION_STYLE}}
+> **Plan**: {{PLAN_TYPE}} · {{PLAN_NAME}} · tier={{PLAN_TIER}}
+> **Stack**: {{PLAN_STACK}}
+> **Default Runtime Profile**: {{RUNTIME_PROFILE}} | Primary worktree warning + optional `.claude/.require-worktree` enforcement + balanced shared hooks
+
+---

package/assets/partials/02-iron-rules.partial.md

@@ -0,0 +1,30 @@
+## Iron Rules
+
+### 1. Good Taste
+- Prefer data structures over branch explosion.
+- More than 3 branches or nesting levels is a refactor signal.
+
+### 2. Pragmatism
+- Solve real constraints first.
+- Keep defaults inferred; ask only override-level questions.
+
+### 3. Zero Compatibility Debt
+- No compatibility shims as default behavior.
+- Use deprecation + replacement routing instead of hidden forks.
+
+### 4. Project-Specific Prohibitions
+
+{{PROHIBITIONS}}
+
+### 5. Detailed Standards (On Demand)
+
+Load these only when needed:
+- `docs/reference-configs/harness-overview.md`
+- `docs/reference-configs/agentic-development-flow.md`
+- `docs/reference-configs/document-generation.md`
+- `docs/reference-configs/global-working-rules.md`
+- `docs/reference-configs/sprint-contracts.md`
+- `docs/reference-configs/evaluator-rubric.md`
+- `docs/reference-configs/handoff-protocol.md`
+
+---

package/assets/partials/03-philosophy.partial.md

@@ -0,0 +1,32 @@
+### 7. Development Protocol
+
+> **Core Philosophy**: Code is toilet paper when contracts change; durable truth belongs in repo-local artifacts, not chat memory.
+
+#### The Layered Truth
+
+- **PRODUCT TRUTH**: `docs/spec.md`
+- **EXECUTION TRUTH**: `plans/`
+- **DONE TRUTH**: `tasks/contracts/`, `tasks/reviews/`, `tasks/notes/`, `.ai/harness/checks/latest.json`, `.ai/harness/runs/`
+- **MUTABLE LAYER**: `src/`
+
+#### Response Protocol (Concise)
+
+```yaml
+NEW_FEATURE_FLOW:
+  1. Define acceptance criteria
+  2. Define contract
+  3. Write failing tests
+  4. Implement and verify
+
+BUG_FIX_FLOW:
+  1. Reproduce with test
+  2. Fix root cause
+  3. Re-run full verification
+```
+
+Detailed playbooks:
+- `docs/reference-configs/harness-overview.md`
+- `docs/reference-configs/agentic-development-flow.md`
+- `docs/reference-configs/sprint-contracts.md`
+
+---

package/assets/partials/04-project-structure.partial.md

@@ -0,0 +1,56 @@
+## Project Structure
+
+```
+{{PROJECT_STRUCTURE}}
+```
+
+### Tech Stack
+
+| Layer | Technology |
+|-------|------------|
+{{TECH_STACK_TABLE}}
+
+{{#IF WEBAPP_RENDERING_MODEL_ENABLED}}
+### Webapp Rendering Model
+
+{{WEBAPP_RENDERING_MODEL_SUMMARY}}
+
+| Boundary | Default |
+|----------|---------|
+{{WEBAPP_RENDERING_TECH_STACK_TABLE}}
+
+{{/IF}}
+{{#IF AI_NATIVE_PROFILE_ENABLED}}
+### AI-Native Profile
+
+{{AI_NATIVE_PROFILE_SUMMARY}}
+
+| Layer | Technology |
+|-------|------------|
+{{AI_NATIVE_TECH_STACK_TABLE}}
+
+{{/IF}}
+---
+
+## Workflow Rules
+
+- Prefer modifying existing files over adding new files.
+- {{RUNTIME_MODE}} by default for file mutations.
+- Primary worktree warns by default; enforce via `.claude/.require-worktree`.
+- Commit explicitly after green checks; no automatic checkpoint hook in the shared preset.
+- Keep stable product truth in `docs/spec.md`.
+- Keep sprint done definitions in `tasks/contracts/`, `tasks/reviews/`, and task-local implementation notes in `tasks/notes/`.
+- Keep resumable state in `.ai/harness/handoff/current.md`.
+- Treat `_ref/` as an occasional ignored external reference checkout cache; read or refresh it for comparison, but keep it out of commits and cite repo+commit/tag+path in `tasks/notes/` or `docs/researches/` when it influences a decision.
+- Treat `deploy/` as the trackable deployment and operations surface for runbooks, submission materials, release checklists, helper scripts, ordered SQL files under `deploy/sql/`, and env examples.
+- Treat `_ops/` as ignored local operations state for secrets, real env files, provider state, artifacts, logs, and scratch files; do not commit or agent-edit `_ops/*`.
+- Treat contract-level execution as worktree-first: `.ai/harness/scripts/plan-to-todo.sh --plan <approved-plan>` starts a linked `codex/<slug>` worktree when policy enables it, and `.ai/harness/scripts/contract-worktree.sh finish` merges back only after Waza `/check` and sprint verification pass.
+- Capture decision-complete Codex Plan mode, Waza `/think`, or `forge-plan` outputs with `.ai/harness/scripts/capture-plan.sh --slug <slug> --title <title>` so planning becomes a `plans/` artifact before implementation.
+- Route product discovery to gstack `office-hours`, complex engineering plans to gstack `plan-eng-review`, design plans to gstack `plan-design-review`, and daily small/medium planning, bug hunts, and checks to Waza `/think`, `/hunt`, and `/check`.
+- Route knowledge sync and handoff retrieval to `gbrain`.
+- Register valuable repo-authored docs in `.ai/harness/brain-manifest.json` with `sync.direction=repo-to-brain`; `.ai/harness/scripts/sync-brain-docs.sh` and the PostEdit hook mirror only those explicit entries into the default brain vault.
+- Codex automation profile is runtime-referenced, not vendored: required skills are `health`, `check`, and `mermaid` from `~/.codex/skills`.
+- CodeGraph is required agent readiness for code navigation; keep `.codegraph/` ignored and use it for P1/P2 discovery, not hook correctness.
+- Treat Waza as Codex-first: `~/.codex/skills` is the Codex runtime source; `~/.agents/skills` is skills CLI staging/cache only.
+- Use `docs/reference-configs/agentic-development-flow.md` for routing details and `docs/reference-configs/external-tooling.md` plus `bash .ai/harness/scripts/check-agent-tooling.sh --host both --check-updates` for environment checks.
+- If repo state conflicts with the task, use an isolated `codex/<task-slug>` worktree, validate with Waza `/check`, and merge back to `main` without unrelated dirty changes.

package/assets/partials/05-workflow.partial.md

@@ -0,0 +1,79 @@
+### Plan Annotation Protocol
+
+Use `docs/researches/` for deep codebase understanding, `docs/spec.md` for stable intent, `plans/` for timestamped execution plans, and `tasks/todos.md` for deferred medium/long-term goals with tradeoffs and revisit triggers.
+
+```yaml
+PLAN_LOOP:
+  MODE: {{RUNTIME_PROFILE}}
+  RECOVERY: {{RECOVERY_PROFILE}}
+  STATE: {{STATE_PROFILE}}
+  CONTEXT: {{CONTEXT_PROFILE}}
+  PHASES: research -> spec -> plan -> contract -> implement -> verify -> check -> review -> handoff
+  RESEARCH_DIR: docs/researches/
+  SPEC_FILE: docs/spec.md
+  PLAN_DIR: plans/
+  PLAN_ARCHIVE: plans/archive/
+  ACTIVE_PLAN_RULE: .ai/harness/active-plan marker is scoped to this worktree; .ai/harness/active-worktree records the owner; legacy .claude/.active-plan is fallback only
+  PLAN_SWITCH: .ai/harness/scripts/switch-plan.sh --plan <plan-file> | --list
+  DEFERRED_LEDGER: tasks/todos.md
+  TODO_ARCHIVE: tasks/archive/
+  CONTRACT_DIR: tasks/contracts/
+  REVIEW_DIR: tasks/reviews/
+  NOTES_DIR: tasks/notes/
+  POLICY_FILE: .ai/harness/policy.json
+  CHECKS_FILE: .ai/harness/checks/latest.json
+  HANDOFF_FILE: .ai/harness/handoff/current.md
+  EVENTS_FILE: .ai/harness/events.jsonl
+  RUNS_DIR: .ai/harness/runs/
+  LESSONS_FILE: tasks/lessons.md
+  CONTEXT_MAP: .ai/context/context-map.json
+  ANNOTATION_GUARD: do not implement until plan Status is "Approved"
+  CONTRACT_GUARD: do not mark done until contract exit criteria pass and review recommends pass
+  EXECUTION_CONTEXT: contract-level work starts in a linked codex/<slug> worktree when policy enables it; primary worktree warning by default; enforce via .claude/.require-worktree
+  CONTRACT_WORKTREE_FINISH: run Waza /check, fill the review artifact from that verdict, then .ai/harness/scripts/contract-worktree.sh finish
+  COMMIT_POLICY: explicit commits after green checks; no automatic checkpoint hook
+```
+
+### Agentic Skill Routing
+
+- Product discovery, early demand shaping, or "is this worth building" -> gstack `office-hours`.
+- Complex engineering plans, architecture lock-in, or cross-module refactors -> gstack `plan-eng-review`.
+- UI/UX or design-system plans -> gstack `plan-design-review`.
+- Small or medium feature plans -> Waza `/think`.
+- Bugs, regressions, crashes, errors, or failing tests -> Waza `/hunt`.
+- Implemented diffs, pre-merge checks, or release follow-through -> Waza `/check`.
+- Architecture diagrams or system-flow diagrams -> Markdown Mermaid first, `mermaid` for optional human HTML.
+- Use P1/P2/P3 as the shared due-diligence protocol; report it explicitly for `plan-eng-review`, `/hunt`, risky refactors, deployments, auth/payment/data work, and shared contracts.
+- Hooks may emit advisory Waza `/check` and `/health` route hints, but must not auto-run skills or vendor skill bodies.
+
+### Task Management Protocol
+
+Core rules (canonical source: see Workflow Orchestration section below):
+- `docs/spec.md` is product truth; `plans/` is execution truth.
+- `tasks/contracts/`, `tasks/reviews/`, and `tasks/notes/` are done gates; hooks are accelerators only.
+- Treat `.ai/harness/active-plan` as authoritative only for its owning worktree; `.ai/harness/active-worktree` records that owner; `.claude/.active-plan` is a legacy fallback during transition.
+- Require plan/contract workflow inventory before implementation: active plan, owning worktree, contract, review, notes, deferred ledger, checks, runs, scope owner, switching rule, and worktree path.
+- Mark done only with verification evidence.
+- Durable progress lives in `tasks/workstreams/`; release history belongs in `docs/CHANGELOG.md`.
+
+### Harness References
+
+- `docs/reference-configs/harness-overview.md`
+- `docs/reference-configs/sprint-contracts.md`
+- `docs/reference-configs/evaluator-rubric.md`
+- `docs/reference-configs/handoff-protocol.md`
+- `docs/reference-configs/changelog-versioning.md`
+- `docs/reference-configs/git-strategy.md`
+- `docs/reference-configs/release-deploy.md`
+- `docs/reference-configs/agentic-development-flow.md`
+- `docs/reference-configs/external-tooling.md`
+
+{{#IF FACTOR_FACTORY_ENABLED}}
+### Factor Research Protocol
+
+- `tasks/factors/registry.json` is the authoritative factor inventory for Plan G projects.
+- Use `bash .ai/harness/scripts/factor-lab-new.sh --name <slug>` to create a candidate workspace.
+- Use `bash .ai/harness/scripts/factor-lab-promote.sh --name <slug>` only after `hypothesis.md` and `backtest-summary.md` exist.
+- Use `bash .ai/harness/scripts/factor-lab-reject.sh --name <slug> --reason "<reason>"` to reject a candidate with an auditable reason.
+- Use `bash .ai/harness/scripts/factor-lab-check.sh` to validate registry state, candidate completeness, and promoted directory drift.
+{{/IF}}

package/assets/partials/06-cloudflare.partial.md

@@ -0,0 +1,20 @@
+## Cloudflare Deployment (Concise Index)
+
+Choose runtime:
+- `Workers` for TanStack Start/Vite SSR webapps, API/webhook/edge logic, and Worker assets
+- `Pages` for static/client-only assets or content shells that do not need Worker SSR
+- `Containers` for Python/ML or heavy dependencies
+
+Recommended combinations:
+- Public landing + authenticated workspace: one `apps/web` Worker (`/` SSR, `/app` client-only)
+- Client-only frontend: `Pages` or Worker static assets by explicit deploy target
+- Frontend + backend runtime: `apps/web` Worker plus separate API/Agent/MCP Workers only when those own authority
+- Full edge stack: Workers + R2/KV/Queues/Durable Objects plus explicit SQL authority
+- AI app: `Workers + AI Gateway + Workers AI + Vectorize`
+
+TanStack Start on Cloudflare uses `@cloudflare/vite-plugin`, `wrangler.jsonc`,
+Worker assets, and `wrangler deploy`; do not use `wrangler pages deploy` for the
+Start SSR app.
+
+Deep docs:
+- `docs/reference-configs/harness-overview.md`

package/assets/partials/07-footer.partial.md

@@ -0,0 +1,38 @@
+## Context Loading Rules
+
+CLAUDE.md is a routing card. Keep context minimal and load only what the current task needs.
+
+### Always Read First
+
+- `docs/spec.md`: stable product truth
+- `tasks/todos.md`: deferred-goal ledger (tradeoff + revisit trigger); the active checklist lives in the plan's `## Task Breakdown`
+- `.ai/harness/handoff/current.md`: resumable cross-session state
+
+### Load On Demand
+
+| Trigger | Read This File |
+|---------|----------------|
+| Deep codebase investigation | `docs/researches/` |
+| Active implementation planning | `plans/plan-*.md` |
+| Sprint done definition | `tasks/contracts/<plan-stem>.contract.md` |
+| Evaluator verdict | `tasks/reviews/<plan-stem>.review.md` |
+| Implementation notes | `tasks/notes/<plan-stem>.notes.md` |
+| Latest verification evidence | `.ai/harness/checks/latest.json` |
+| Historical implementation context | `plans/archive/` and `tasks/archive/` |
+| Agentic skill routing | `docs/reference-configs/agentic-development-flow.md` |
+| Harness runtime model | `docs/reference-configs/harness-overview.md` |
+| Sprint contract rules | `docs/reference-configs/sprint-contracts.md` |
+| Evaluator scoring | `docs/reference-configs/evaluator-rubric.md` |
+| Handoff expectations | `docs/reference-configs/handoff-protocol.md` |
+| Product and architecture context | `docs/brief.md`, `docs/decisions.md`, `docs/tech-stack.md` |
+| Durable progress and release history | `tasks/workstreams/`, `docs/CHANGELOG.md` |
+
+### First Principles
+
+- Keep state minimal and derivable.
+- Keep interfaces explicit and verifiable.
+
+---
+
+*Template Version: {{TEMPLATE_VERSION}}*
+*Generated by forge@{{SKILL_VERSION}}*

package/assets/partials/08-orchestration.partial.md

@@ -0,0 +1,49 @@
+## Workflow Orchestration
+
+### 1. Research Before Planning
+- Deeply read relevant code paths and persist findings to `docs/researches/`.
+- Capture hidden contracts, edge cases, and integration risks before updating `docs/spec.md` or proposing execution.
+
+### 2. Annotation Cycle
+- Iterate plan updates directly in `plans/plan-*.md` via inline notes.
+- Treat `.ai/harness/active-plan` as authoritative for this worktree when present; `.ai/harness/active-worktree` records the owning worktree; `.claude/.active-plan` is a legacy fallback during transition.
+- Switch between concurrent plans with `bash .ai/harness/scripts/switch-plan.sh --plan <plan-file>`.
+- Fill the plan/contract workflow inventory before implementation.
+- Do not implement while plan status is `Draft` or `Annotating`.
+
+### 3. Plan Node Default
+- Enter plan mode for non-trivial tasks.
+- If no stable product truth exists, run `bash .ai/harness/scripts/new-spec.sh`.
+- When Codex Plan mode or Waza `/think` reaches a decision-complete plan, capture it with `bash .ai/harness/scripts/capture-plan.sh --slug <slug> --title <title>` and the plan text on stdin.
+- If no captured active execution plan exists, run `bash .ai/harness/scripts/new-plan.sh --slug <slug> --title <title>` or capture a finished planning note with `bash .ai/harness/scripts/capture-plan.sh`.
+- If the user asks for a Sprint backlog, run `bash .ai/harness/scripts/new-sprint.sh --slug <slug> --title <title>`; it writes `plans/sprints/*.sprint.md`, not `plans/plan-*.md`.
+- When the user approves implementation, run `bash .ai/harness/scripts/plan-to-todo.sh --plan <active-plan>` or capture the approved plan with `--status Approved --execute`; this creates contract/review/notes scaffolding and leaves plan tasks in `## Task Breakdown`.
+- Re-plan when execution drifts.
+
+### 4. Research Delegation Strategy
+- The main agent decides whether to spawn based on task breadth, context impact, raw-log volume, and callable runner availability.
+- Keep one ownership boundary per spawned sidecar.
+- Do not ask the user for spawn confirmation. If no sidecar runner is callable or spawning is not worth the context cost, perform the same bounded research trace in the main thread and persist conclusions to `docs/researches/`.
+- Recovery profile: `{{RECOVERY_PROFILE}}`.
+- State profile: `{{STATE_PROFILE}}`.
+
+### 5. Self-Improvement Loop
+- Append correction-derived rules to `tasks/lessons.md`.
+
+### 6. Verification Before Done
+- No task completion without test/build evidence.
+
+### 6b. Contract Verification
+- Define per-sprint contract files in `tasks/contracts/`.
+- Verify contract exit criteria before claiming completion.
+- Require Waza `/check` to produce the matching evaluator review before any done/completed response.
+- Use `.ai/harness/scripts/verify-contract.sh --contract tasks/contracts/{plan-stem}.contract.md --strict`.
+
+### 7. Balanced Elegance
+- Redesign hacky non-trivial fixes before shipping.
+
+### 8. Autonomous Bug Fixing
+- Start fixing when logs/tests provide sufficient evidence.
+
+Detailed patterns:
+- `docs/reference-configs/harness-overview.md`

package/assets/partials/09-compact-instructions.partial.md

@@ -0,0 +1,11 @@
+## Compact Memory
+
+When compressing context, preserve information in this order:
+
+1. Architecture decisions and irreversible constraints
+2. Files already modified or generated
+3. Verification status, failing checks, and open contract gaps
+4. Remaining TODOs and follow-up risks
+5. Tool output only as conclusions, not raw logs
+
+Never rename identifiers, paths, plan slugs, contract filenames, or other established references during compression.

package/assets/partials/_assembly-order.md

@@ -0,0 +1,40 @@
+# Partial Assembly Order
+
+This document defines the order used to assemble `CLAUDE.md`.
+
+## Assembly Sequence
+
+```
+1. 01-header.partial.md
+2. 02-iron-rules.partial.md
+3. 03-philosophy.partial.md
+4. 04-project-structure.partial.md
+5. 05-workflow.partial.md
+6. {{#IF CLOUDFLARE_NATIVE}}06-cloudflare.partial.md{{/IF}}
+7. 07-footer.partial.md
+8. 08-orchestration.partial.md
+9. 09-compact-instructions.partial.md
+```
+
+## Conditional Logic
+
+Cloudflare section is included when:
+- The selected plan has `cloudflareNative=true` in `assets/plan-map.json`
+- Or explicit `--cloudflare`
+
+It is excluded when:
+- The selected plan has `cloudflareNative=false`
+- Or explicit `--no-cloudflare`
+
+## Variable Substitution
+
+1. Concatenate partials in order
+2. Process conditional blocks `{{#IF CONDITION}}...{{/IF}}`
+3. Replace `{{VARIABLE_NAME}}` placeholders
+4. Output final markdown
+
+## Rules
+
+- Partials are flat files; no partial includes
+- One conceptual purpose per partial
+- Keep core rules concise and move details to the harness reference docs under `docs/reference-configs/*`

package/assets/partials-agents/01-header.partial.md

@@ -0,0 +1,8 @@
+# AGENTS Operating Guide: {{PROJECT_NAME}}
+
+> **Developer**: {{USER_NAME}}
+> **Service Target**: {{SERVICE_TARGET}}
+> **Interaction Style**: {{INTERACTION_STYLE}}
+> **Plan**: {{PLAN_TYPE}} · {{PLAN_NAME}} · tier={{PLAN_TIER}}
+
+---

package/assets/partials-agents/02-operating-mode.partial.md

@@ -0,0 +1,44 @@
+## Operating Mode
+
+- Default to **{{RUNTIME_MODE}}**.
+- Runtime profile: {{RUNTIME_PROFILE}}.
+- Recovery profile: `{{RECOVERY_PROFILE}}`.
+- State profile: `{{STATE_PROFILE}}`.
+- Context profile: `{{CONTEXT_PROFILE}}`.
+- Claude runtime expectation: `{{CLAUDE_POLICY}}`.
+- Codex runtime expectation: `{{CODEX_POLICY}}`.
+- Do not implement until the user explicitly asks to implement.
+- Stable product truth: `docs/spec.md`.
+- Research reports: `docs/researches/`.
+- Deferred-goal ledger: `tasks/todos.md` (active execution stays in the plan's `## Task Breakdown`).
+- Task contract done gate: `tasks/contracts/` (legacy name: sprint contract).
+- Evaluator verdicts: `tasks/reviews/`.
+- Implementation notes: `tasks/notes/`.
+- Structured checks: `.ai/harness/checks/latest.json`.
+- Session handoff: `.ai/harness/handoff/current.md`.
+- Harness policy: `.ai/harness/policy.json`.
+- Context map: `.ai/context/context-map.json`.
+- Lessons contract: `tasks/lessons.md`.
+- Plan directory: `plans/` (timestamped plans).
+- Active plan rule: `.ai/harness/active-plan` for this worktree when present, `.ai/harness/active-worktree` as owner marker, and `.claude/.active-plan` legacy fallback during transition. Do not infer active execution from the latest plan.
+- Plan archive: `plans/archive/`.
+- Todo archive: `tasks/archive/`.
+- Shared automation layer: `.ai/hooks/`.
+- Host adapters: user-level `~/.claude/settings.json` and `~/.codex/hooks.json` call `forge-hook`, falling back to `forge hook`, which dispatches into opted-in repos.
+- External reference cache: `_ref/` is an occasional ignored external checkout cache, read/refresh-only comparison material, and must stay out of commits; decisions based on it must cite repo+commit/tag+path in notes or research.
+- Deployment operations workspace: `deploy/` is commit-ready for runbooks, submission materials, release checklists, helper scripts, ordered SQL files under `deploy/sql/`, and env examples.
+- Local operations state: `_ops/` is ignored and private for secrets, real env files, provider state, artifacts, logs, and scratch files; do not commit or agent-edit `_ops/*`.
+- Agentic skill routing: product discovery -> gstack `office-hours`; complex engineering plans -> gstack `plan-eng-review`; design plans -> gstack `plan-design-review`; daily small/medium planning, bug hunts, and checks -> Waza `/think`, `/hunt`, `/check`.
+- Knowledge sync and handoff retrieval -> `gbrain`.
+- Codex automation profile: required `health`, `check`, and `mermaid` from `~/.codex/skills`; do not vendor skill bodies.
+- CodeGraph readiness: required for agent code navigation; keep `.codegraph/` ignored and use `codegraph sync/context/query/callers/callees/impact` for P1/P2 discovery.
+- External tooling reference: `docs/reference-configs/agentic-development-flow.md` for routing details, `docs/reference-configs/external-tooling.md` for install/update guidance.
+- Waza runtime boundary: Codex reads `~/.codex/skills`; `~/.agents/skills` is only skills CLI staging/cache and must be copied into Codex with verification after updates.
+- Environment check: `bash .ai/harness/scripts/check-agent-tooling.sh --host both --check-updates`.
+- After substantive repo changes, run `bash .ai/harness/scripts/check-task-sync.sh` and `bash .ai/harness/scripts/check-task-workflow.sh --strict`.
+- Primary worktree warns by default; enforce via `.claude/.require-worktree`.
+- Contract-level execution is worktree-first: `.ai/harness/scripts/plan-to-todo.sh --plan <approved-plan>` starts a linked `codex/<slug>` worktree when policy enables it, and `.ai/harness/scripts/contract-worktree.sh finish` merges back only after Waza `/check` and sprint verification pass.
+- After Codex Plan mode, Waza `/think`, or `forge-plan` produces a decision-complete plan, capture it with `.ai/harness/scripts/capture-plan.sh --slug <slug> --title <title>`; if implementation is already approved, capture with `--status Approved --execute` or run `.ai/harness/scripts/plan-to-todo.sh --plan <active-plan>`.
+- If repo state conflicts with the task, use an isolated `codex/<task-slug>` worktree, validate with Waza `/check`, and merge back to `main` without unrelated dirty changes.
+
+---

package/assets/partials-agents/03-orchestration.partial.md

@@ -0,0 +1,45 @@
+## Workflow Orchestration
+
+### 1. Research Before Planning
+- Deeply inspect relevant code and persist findings in `docs/researches/`.
+- Avoid implementation before research, spec, plan, and contract are complete.
+
+### 2. Annotation Cycle
+- Keep active plans in `plans/plan-*.md` and iterate with inline notes.
+- Treat `.ai/harness/active-plan` as authoritative for this worktree when present; `.ai/harness/active-worktree` records the owning worktree; `.claude/.active-plan` is a legacy fallback during transition.
+- Resolve annotations before implementation.
+
+### 3. Plan Node Default
+- Enter plan mode for non-trivial tasks.
+- If `docs/spec.md` is missing, run `bash .ai/harness/scripts/new-spec.sh` first.
+- Capture decision-complete Codex Plan mode or Waza `/think` output with `bash .ai/harness/scripts/capture-plan.sh --slug <slug> --title <title>`; if no captured active execution plan exists, use `new-plan.sh`; after approval, run `plan-to-todo.sh` or capture with `--status Approved --execute`.
+- Use `new-sprint.sh` only for Sprint backlogs; it writes `plans/sprints/*.sprint.md`, while PRDs stay in `plans/prds/`.
+- Keep active checklist items in the active plan's `## Task Breakdown`; record only deferred goals in `tasks/todos.md`.
+
+### 4. Research Delegation Strategy
+- The main agent decides whether to spawn based on task breadth, context impact, raw-log volume, and callable runner availability.
+- Parallelize only non-dependent paths.
+- Do not ask the user for spawn confirmation. If no sidecar runner is callable or spawning is not worth the context cost, do the same bounded trace in the main thread and write conclusions to `docs/researches/`.
+
+### 4b. Durable Handoff
+- Treat auto-compact as an unreliable fallback.
+- Before switching sessions or worktrees, refresh `.ai/harness/handoff/current.md` and `.ai/harness/handoff/resume.md`, then resume from the filesystem artifacts.
+
+### 5. Self-Improvement Loop
+- After correction, append prevention rule to `tasks/lessons.md`.
+
+### 6. Verification Before Done
+- No completion without verification evidence.
+
+### 6b. Contract Verification
+- Use task contracts in `tasks/contracts/` as completion gates.
+- Use implementation notes in `tasks/notes/` for task-local decisions that should not automatically become memory.
+- Validate exit criteria and the Waza `/check` review recommendation before any done/completed response.
+
+### 7. Balanced Elegance
+- Redesign hacky non-trivial fixes before shipping.
+
+### 8. Autonomous Bug Fixing
+- Start fixes when logs/errors/tests are sufficient.
+
+---