Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 19 additions & 7 deletions docs/memory/_shared/context-loading.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
description: "Smart context loading convention — descriptive 7-file always-load layer (skill file wins; exception set rule-derived from skill files, never enumerated in the preamble — d9rs), opt-in skill helpers (6-value allowlist incl. `_srad`/`_pipeline`) + stage-conditional loading, standard subagent context (orchestrators incl. `/fab-proceed`), per-stage model resolution at the dispatch seam (`fab resolve-agent <stage>`, provider-neutral, Claude-Code adapter named, review-resolves-once — l3ja; applies on every post-intake stage since the single-dispatch collapse, advisory only for a genuinely no-dispatch run — fgxx; the two halves dispatch through two seams — model via the Agent `model` param (short alias opus/sonnet/haiku/fable, id→alias mapped at the seam), effort via an imperative subagent-prompt instruction (no Agent effort param; omit when empty), plus a compliance-visibility expectation that each site surface the resolved `model=/effort=` — m3d4; residual = a per-sub-agent effort param on the Agent tool, a harness ask), selective domain loading, SRAD protocol pointer, scoped Next Steps Convention, generic fab-command failure rule (unconditional non-zero exit → STOP; `fab log command` exits 0 by contract)"
description: "Smart context loading convention — descriptive 7-file always-load layer (skill file wins; exception set rule-derived from skill files, never enumerated in the preamble — d9rs), opt-in skill helpers (7-value allowlist incl. `_srad`/`_pipeline`/`_intake`) + stage-conditional loading, standard subagent context (orchestrators incl. `/fab-proceed`), per-stage model resolution at the dispatch seam (`fab resolve-agent <stage>`, provider-neutral, Claude-Code adapter named, review-resolves-once — l3ja; applies on every post-intake stage since the single-dispatch collapse, advisory only for a genuinely no-dispatch run — fgxx; the two halves dispatch through two seams — model via the Agent `model` param (short alias opus/sonnet/haiku/fable, id→alias mapped at the seam), effort via an imperative subagent-prompt instruction (no Agent effort param; omit when empty), plus a compliance-visibility expectation that each site surface the resolved `model=/effort=` — m3d4; residual = a per-sub-agent effort param on the Agent tool, a harness ask), selective domain loading, SRAD protocol pointer, scoped Next Steps Convention, generic fab-command failure rule (unconditional non-zero exit → STOP; `fab log command` exits 0 by contract)"
---
# Context Loading

Expand Down Expand Up @@ -33,22 +33,33 @@ The only universal helper beyond the 7 project files is `_preamble.md`. Addition

### Skill Helper Declaration (Opt-In)

Skills declare additional helper files via the `helpers:` frontmatter list. Allowed values (six since 260611-szxd, which added `_pipeline`): `_generation`, `_review`, `_cli-fab`, `_cli-external`, `_srad`, `_pipeline`. The agent MUST read `.claude/skills/{helper}/SKILL.md` for each declared helper after reading `_preamble` and before executing the skill body.
Skills declare additional helper files via the `helpers:` frontmatter list. Allowed values (seven since 260613-3xaj, which added `_intake`; six since 260611-szxd, which added `_pipeline`): `_generation`, `_review`, `_cli-fab`, `_cli-external`, `_srad`, `_pipeline`, `_intake`. The agent MUST read `.claude/skills/{helper}/SKILL.md` for each declared helper after reading `_preamble` and before executing the skill body.

**Stage-conditional loading** (260611-zc9m): a skill MAY instead load a helper at its point of use via an explicit in-body read instruction (e.g., "read `.claude/skills/_review/SKILL.md` before entering Review Behavior"). Frontmatter `helpers:` declares unconditional pre-body loads; in-body read instructions declare conditional ones — a helper loaded this way is intentionally absent from the frontmatter list, so the frontmatter contract stays honest. `/fab-continue` is the sole current user: `_generation` at apply entry / intake-`active` regeneration, `_review` at Review Behavior entry (see [pipeline/execution-skills.md](../pipeline/execution-skills.md)).

Current mapping (post-260611-szxd):
Current mapping (post-260613-3xaj):

| Skill(s) | `helpers:` |
|----------|------------|
| `fab-new`, `fab-draft` | `[_generation, _srad]` |
| `fab-new`, `fab-draft` | `[_generation, _srad, _intake]` (3xaj added `_intake`; both keep `_generation`/`_srad` declared directly — the `_pipeline` precedent, consumers declare underlying helpers rather than inheriting transitively) |
| `fab-continue` | `[_srad]` (+ point-of-use in-body reads of `_generation`/`_review`) |
| `fab-ff`, `fab-fff` | `[_generation, _review, _srad, _pipeline]` (orchestrator-level rework edits `plan.md` sections directly, so `_generation` stays unconditional — finding f074 refuted; `_pipeline` is the shared ff/fff pipeline bracket and constitutes the wrappers' entire body, so its load is unconditional by construction — szxd) |
| `fab-clarify` | `[_srad]` |
| `fab-operator` | `[_cli-fab, _cli-external]` |
| All others (17 skills) | omitted / `[]` (load only `_preamble`) |
| All others (16 skills) | omitted / `[]` (load only `_preamble`) |

`_naming` and `_cli-rk` are NOT allowed values — their content is inlined into `_preamble`. `_preamble` itself is implicit and never listed.
`_naming` and `_cli-rk` are NOT allowed values — their content is inlined into `_preamble`. `_preamble` itself is implicit and never listed. `/fab-proceed` declares **no** `helpers:` (it dispatches `_intake` as a subagent prompt — the subagent reads the helper — exactly as it dispatched `/fab-new` before 3xaj). The internal helpers `_generation`, `_review`, `_pipeline`, and `_intake` themselves carry no `helpers:` frontmatter — they reference what they need in-body and rely on the consumer (or dispatched subagent) having loaded it.

**One shared helper per pipeline phase (completed by 3xaj).** The four internal orchestration/mechanics helpers decompose the workflow symmetrically — each is a shared body parameterized by call-site-specific knobs, with call-site tails staying in the consumer files:

| Phase | Helper | Knob(s) | Consumers |
|-------|--------|---------|-----------|
| artifact mechanics | `_generation` | — | `fab-new`, `fab-draft`, `fab-continue`, `fab-ff`, `fab-fff` |
| review mechanics | `_review` | — | `fab-continue`, `fab-ff`, `fab-fff` |
| **pre-intake orchestration** | **`_intake`** | `{questioning-mode}` | `fab-new`, `fab-draft`, `fab-proceed` |
| post-intake orchestration | `_pipeline` | `{driver}`, `{terminal}` | `fab-ff`, `fab-fff` |

`_intake` (3xaj) is the **pre-boundary** counterpart to the **post-boundary** `_pipeline` (szxd): intake is the single context-bearing boundary in the pipeline; everything up to and including intake creation runs in the main session context (pre-boundary: `_intake`), everything after runs as dispatched subagents over the intake artifact (post-boundary: `_pipeline`). Both extractions mirror the same shape (shared body + one-or-two knobs + call-site tails). See [pipeline/planning-skills.md](../pipeline/planning-skills.md) § The `_intake` Shared Create-Intake Procedure for the full pre-boundary decomposition.

### Preflight Script for Change Context

Expand Down Expand Up @@ -83,7 +94,7 @@ This applies to all skills operating on an active change, not just spec-writing

### Standard Subagent Context

When orchestrator skills (`/fab-ff`, `/fab-fff`, and the prefix-step orchestrator `/fab-proceed` — added to the preamble's § Subagent Dispatch orchestrator list in d9rs; it dispatches `/fab-new`, `/fab-switch`, and `/git-branch` as prefix steps before delegating) or middle agents (`/fab-continue`) dispatch subagents via the Agent tool, the subagent prompt MUST instruct the subagent to read a standard set of project files **before** executing its task. This is defined in `_preamble.md` § Standard Subagent Context and is distinct from the Always Load layer (which is for the parent agent itself).
When orchestrator skills (`/fab-ff`, `/fab-fff`, and the prefix-step orchestrator `/fab-proceed` — added to the preamble's § Subagent Dispatch orchestrator list in d9rs; it dispatches the `_intake` Create-Intake Procedure (3xaj — was the full `/fab-new` skill), `/fab-switch`, and `/git-branch` as prefix steps before delegating) or middle agents (`/fab-continue`) dispatch subagents via the Agent tool, the subagent prompt MUST instruct the subagent to read a standard set of project files **before** executing its task. This is defined in `_preamble.md` § Standard Subagent Context and is distinct from the Always Load layer (which is for the parent agent itself).

The standard subagent context includes:

Expand Down Expand Up @@ -218,6 +229,7 @@ The exception set is **declared by the skill files themselves** (the preamble ne

| Change | Date | Summary |
|--------|------|---------|
| 260613-3xaj-extract-intake-helper | 2026-06-13 | **Helper allowlist grows to seven values**: `_intake` added to the `_preamble.md` § Skill Helper Declaration allowed values (`_generation`, `_review`, `_cli-fab`, `_cli-external`, `_srad`, `_pipeline`, `_intake`). The new `_intake.md` internal helper holds the shared pre-boundary Create-Intake Procedure (fab-new Steps 0–9, parameterized by `{questioning-mode}`); `fab-new`/`fab-draft` declare `helpers: [_generation, _srad, _intake]` (keep declaring `_generation`/`_srad` directly per the `_pipeline` precedent), `_intake` itself carries no `helpers:`, and `/fab-proceed` keeps none (dispatches `_intake` as a subagent prompt). Helper mapping table updated (fab-new/fab-draft row; "all others" 17→16). Added the **one-shared-helper-per-pipeline-phase symmetry table** (`_generation`/`_review`/`_intake`/`_pipeline`) — `_intake` is the pre-boundary counterpart to the post-boundary `_pipeline`, both mirroring the shared-body + knob + call-site-tail shape. Standard Subagent Context prefix-step list updated (`/fab-proceed` dispatches `_intake`, not full `/fab-new`). See [pipeline/planning-skills.md](../pipeline/planning-skills.md) § The `_intake` Shared Create-Intake Procedure. |
| 260613-m3d4-uniform-stage-model-tier | 2026-06-13 | **Per-Stage Model Resolution gains the two-seam dispatch contract + compliance visibility** (Change C — skills/docs prose only, no Go; gated on `260613-fgxx`). The resolved tier's **two halves now dispatch through two seams**: the **model** rides the Agent tool's `model` param (unchanged), the **effort** is injected as an imperative instruction in the subagent prompt (``Operate at `<effort>` reasoning effort for this task.``, omitted when empty) — closing Gap 2's effort half, which fgxx had left as a deferred follow-up (the Agent tool has no `effort` param). Added a **compliance-visibility** expectation (Gap 1b): every dispatch site surfaces the resolved `model=/effort=` (into the dispatch prompt and/or step output) so a skipped/mis-resolved `fab resolve-agent` call is visible rather than silent, plus a prose all-empty-resolution surface/assert note (no Go guard — dispatch is harness-internal). Harness-adapter boundary now records the **id→alias** detail (the `model` param takes `opus`/`sonnet`/`haiku`/`fable`, not the full `claude-*` id the resolver emits — the orchestrator maps at the seam) and names the prompt as the effort adapter. The lone residual is the **harness ask** — a first-class per-sub-agent `effort` param on the Agent tool, out of fab's control, not built. Mirrors `_preamble.md` § Per-Stage Model Resolution; the `_pipeline.md`/`fab-ff`/`fab-fff`/`fab-continue` dispatch sites and their SPEC mirrors carry the same two-seam phrasing (see [pipeline/execution-skills.md](../pipeline/execution-skills.md)); `docs/findings/per-stage-model-tier-application.md` and `docs/specs/stage-models.md` reconciled to this reality. |
| 260613-fgxx-collapse-post-intake-dual-mode | 2026-06-13 | **Per-Stage Model Resolution reconciled to the single post-intake dispatch mode** (minimal reconcile — full uniform-tier closure deferred to a follow-up). The "Foreground is advisory-only" paragraph (and its `description:` frontmatter mention) is rewritten: since fgxx collapsed the post-intake dual execution mode, **every** post-intake stage dispatches a sub-agent — including plain `/fab-continue`, now a one-stage sequencer that resolves `fab resolve-agent <stage>` and dispatches its stage's block — so per-stage selection applies uniformly across apply/review/hydrate regardless of caller, and the residual advisory case narrows to a stage skill genuinely run with no dispatch at all. Intake stays pre-boundary (not tiered). Does NOT write the full uniform-tiering / per-sub-agent-effort-knob story. Mirrors `_preamble.md` § Per-Stage Model Resolution (see [pipeline/execution-skills.md](../pipeline/execution-skills.md) for the fab-continue rewrite). |
| 260613-l3ja-per-stage-model-tiers | 2026-06-13 | New **Per-Stage Model Resolution** requirements section documenting the sub-agent dispatch-seam wiring (`_preamble.md` § Subagent Dispatch → Per-Stage Model Resolution): the orchestrators (`/fab-ff`, `/fab-fff`, `/fab-proceed`) and `/fab-continue`'s dispatch run `fab resolve-agent <stage>` immediately before each stage's sub-agent and pass the resolved `model=`/`effort=` (empty model ⇒ omit/inherit; empty effort ⇒ omit). The resolution is **provider-neutral**; the Claude Code adapter (Agent tool `model` param) is named as harness-specific, not universal — and the coupling is not new (fab's dispatch is already Claude-Code-shaped). `review` resolves **once** for both reviewers + merge; foreground runs are advisory-only (MAY note mismatch, MUST NOT switch). The config schema + rationale live in [configuration.md](configuration.md). |
Expand Down
2 changes: 1 addition & 1 deletion docs/memory/_shared/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,4 @@ description: "Cross-cutting concerns spanning all domains — config.yaml/consti
| File | Description | Last Updated |
|------|-------------|-------------|
| [configuration](configuration.md) | `config.yaml` schema (incl. `fab_version`, `review_tools`, `true_impact_exclude`, `test_paths`, `stage_hooks`, `agent.tiers` per-stage-model override — sole surface, per-field merge over fab-kit defaults, NO validation/provider-neutral, fixed non-overridable stage→tier mapping, l3ja; `stage_directives` + `model_tiers` removed in c5tr via migration 2.1.6-to-2.2.0), single fab-module parser `internal/config` + nil-safe accessors incl. the coupled-Unmarshal fallback caveat (ye8r), companion files (`context.md`, `code-quality.md`, `code-review.md` incl. `## Parsimony Pass` toggle and the wired `## Rework Budget` Max-cycles knob), `constitution.md` governance, 5 Cs of Quality, lifecycle management | 2026-06-13 |
| [context-loading](context-loading.md) | Smart context loading convention — descriptive 7-file always-load layer (skill file wins; exception set rule-derived from skill files, never enumerated in the preamble — d9rs), opt-in skill helpers (6-value allowlist incl. `_srad`/`_pipeline`) + stage-conditional loading, standard subagent context (orchestrators incl. `/fab-proceed`), per-stage model resolution at the dispatch seam (`fab resolve-agent <stage>`, provider-neutral, Claude-Code adapter named, review-resolves-once — l3ja; applies on every post-intake stage since the single-dispatch collapse, advisory only for a genuinely no-dispatch run — fgxx; the two halves dispatch through two seams — model via the Agent `model` param (short alias opus/sonnet/haiku/fable, id→alias mapped at the seam), effort via an imperative subagent-prompt instruction (no Agent effort param; omit when empty), plus a compliance-visibility expectation that each site surface the resolved `model=/effort=` — m3d4; residual = a per-sub-agent effort param on the Agent tool, a harness ask), selective domain loading, SRAD protocol pointer, scoped Next Steps Convention, generic fab-command failure rule (unconditional non-zero exit → STOP; `fab log command` exits 0 by contract) | 2026-06-13 |
| [context-loading](context-loading.md) | Smart context loading convention — descriptive 7-file always-load layer (skill file wins; exception set rule-derived from skill files, never enumerated in the preamble — d9rs), opt-in skill helpers (7-value allowlist incl. `_srad`/`_pipeline`/`_intake`) + stage-conditional loading, standard subagent context (orchestrators incl. `/fab-proceed`), per-stage model resolution at the dispatch seam (`fab resolve-agent <stage>`, provider-neutral, Claude-Code adapter named, review-resolves-once — l3ja; applies on every post-intake stage since the single-dispatch collapse, advisory only for a genuinely no-dispatch run — fgxx; the two halves dispatch through two seams — model via the Agent `model` param (short alias opus/sonnet/haiku/fable, id→alias mapped at the seam), effort via an imperative subagent-prompt instruction (no Agent effort param; omit when empty), plus a compliance-visibility expectation that each site surface the resolved `model=/effort=` — m3d4; residual = a per-sub-agent effort param on the Agent tool, a harness ask), selective domain loading, SRAD protocol pointer, scoped Next Steps Convention, generic fab-command failure rule (unconditional non-zero exit → STOP; `fab log command` exits 0 by contract) | 2026-06-13 |
2 changes: 1 addition & 1 deletion docs/memory/memory-docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,4 +11,4 @@ description: "Authoring docs/memory & docs/specs — the hydrate skills (ingest
| [hydrate-generate](hydrate-generate.md) | `/docs-hydrate-memory` generate mode — codebase scanning, gap detection, interactive scoping, memory file generation + placement rules (target path, domain/sub-domain index stubs, shape bounds — d9rs) | 2026-06-12 |
| [hydrate-specs](hydrate-specs.md) | `/docs-hydrate-specs` skill — structural gap detection between memory and specs, interactive propose-then-apply (incl. the no-target new-spec-file branch and aligned prompt/handler tokens — d9rs) | 2026-06-12 |
| [specs-index](specs-index.md) | `docs/specs/` directory — pre-implementation specs, distinction from memory, bootstrap and context integration, per-skill SPEC mirror coverage + naming policy (`SPEC-{source-filename}.md`; `_cli-fab`/`_cli-external` excluded — uliv); mirrors are reserved paths for `docs-reorg-specs` (d9rs) | 2026-06-12 |
| [templates](templates.md) | Artifact templates (intake, plan), skill frontmatter, and memory file format (incl. `description:` frontmatter + generated domains-only index, tciy). `plan.md` (`## Requirements` + `## Tasks` + `## Acceptance` + optional review-owned `## Deletion Candidates`) absorbs the former `spec.md` (j6cs) and the prior `tasks.md` + `checklist.md` pair; acceptance R# mandate scoped to requirement-derived categories, plan Assumptions = three grades, no Status header lines (uliv) | 2026-06-12 |
| [templates](templates.md) | Artifact templates (intake, plan), skill frontmatter (incl. `helpers:` + the one-shared-helper-per-phase decomposition `_generation`/`_review`/`_intake`/`_pipeline`, symmetry completed by 3xaj), and memory file format (incl. `description:` frontmatter + generated domains-only index, tciy). `plan.md` (`## Requirements` + `## Tasks` + `## Acceptance` + optional review-owned `## Deletion Candidates`) absorbs the former `spec.md` (j6cs) and the prior `tasks.md` + `checklist.md` pair; acceptance R# mandate scoped to requirement-derived categories, plan Assumptions = three grades, no Status header lines (uliv) | 2026-06-12 |
Loading
Loading