From 5be6dbaec5de81e2ed150b7fe8d3304466077ef9 Mon Sep 17 00:00:00 2001 From: Marlin Forbes Date: Sat, 2 May 2026 09:46:23 +0200 Subject: [PATCH 1/2] docs(harness): add spatial-vs-temporal context taxonomy Closes #7 --- skills/harness/README.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/skills/harness/README.md b/skills/harness/README.md index c571ada..183043a 100644 --- a/skills/harness/README.md +++ b/skills/harness/README.md @@ -24,6 +24,34 @@ The day-to-day patterns this skill ships came from these voices, who keep publis This skill is also a sibling of [datashaman/harness-template](https://github.com/datashaman/harness-template) — that repo is the *project-scope* harness (drop-in stack profiles, `harness/policies/`, `scripts/harness-check.sh`, `harness/grades.yml`). `/harness` is the user-scope counterpart. +## Context model: spatial vs temporal + +The harness manages context on two axes. Naming them gives design discussions vocabulary ("is this a spatial concern or a temporal one?") and makes coverage gaps visible at a glance. Hooks aren't on either table — they're *sensors* (feedback), not context surfaces; they're documented under install below. + +**Spatial — what occupies the window in a given turn:** + +| Surface | Always loaded? | Notes | +| ----------------------- | ----------------------------- | ------------------------------------------------------------------ | +| `~/.claude/CLAUDE.md` | yes | user-scope operating contract | +| `/CLAUDE.md` | yes (when in that project) | project-scope override | +| `MEMORY.md` (index) | yes | pointers to memory entries, not the entries themselves | +| Memory entries | on demand | loaded when the agent decides they're relevant | +| Skills | on demand | progressive disclosure — `SKILL.md` frontmatter triggers the load | +| System prompt | yes | tools + harness instructions | + +**Temporal — what survives across boundaries:** + +| Boundary | Mechanism | +| --------------------------------- | --------------------------------------------------------------------------------- | +| Autocompact (mid-session) | `post-compact-reinject.sh` — re-cats `CLAUDE.md` / `AGENTS.md` / `~/.claude/CLAUDE.md` | +| Between tool steps (mid-session) | `/critique` — deliberate critique pass without waiting for Stop (PTC, see #6) | +| Session end → next session | auto-memory write — agent stores durable facts to `memory/` | +| Across sessions | `memory/` store + `MEMORY.md` index | +| Memory hygiene over time | `memoize` sub-action (deterministic) + weekly remote routine (semantic) | +| Config drift over time | `snapshot` (mirror to private repo) + monthly remote `audit` routine | + +The PTC loop named in `CLAUDE.md` cuts across these axes: **Plan** is spatial preparation (load the right context before editing), **Tool** is the work itself, **Critique** is *temporal* — carrying findings forward, at session boundaries (Stop gate, `advisor()`) and intra-session via `/critique`. + ## When to use `/harness` — the skill detects intent from your phrasing. Examples: From a5ff02b7a80037880f67fa1b878a7c60cbb8db2f Mon Sep 17 00:00:00 2001 From: Marlin Forbes Date: Sat, 2 May 2026 09:55:13 +0200 Subject: [PATCH 2/2] fix(harness): address Copilot review on PR #10 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Reframe the hooks-on-feedback-axis claim: post-compact-reinject.sh is a hook implementing a context-preservation mechanism, so it stays in the temporal table; sensor hooks remain off both tables. - Add AGENTS.md to the spatial table — referenced in the temporal mechanism (post-compact reinjection) but was missing from spatial. --- skills/harness/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/skills/harness/README.md b/skills/harness/README.md index 183043a..6e0f499 100644 --- a/skills/harness/README.md +++ b/skills/harness/README.md @@ -26,7 +26,7 @@ This skill is also a sibling of [datashaman/harness-template](https://github.com ## Context model: spatial vs temporal -The harness manages context on two axes. Naming them gives design discussions vocabulary ("is this a spatial concern or a temporal one?") and makes coverage gaps visible at a glance. Hooks aren't on either table — they're *sensors* (feedback), not context surfaces; they're documented under install below. +The harness manages context on two axes. Naming them gives design discussions vocabulary ("is this a spatial concern or a temporal one?") and makes coverage gaps visible at a glance. Most hooks are *sensors* on the feedback axis — they're documented under install below, not here. The one exception is `post-compact-reinject.sh`: implemented as a hook, but its job is *context preservation*, so it sits in the temporal table. **Spatial — what occupies the window in a given turn:** @@ -34,6 +34,7 @@ The harness manages context on two axes. Naming them gives design discussions vo | ----------------------- | ----------------------------- | ------------------------------------------------------------------ | | `~/.claude/CLAUDE.md` | yes | user-scope operating contract | | `/CLAUDE.md` | yes (when in that project) | project-scope override | +| `/AGENTS.md` | yes (when present) | sibling to project CLAUDE.md; re-injected after autocompact | | `MEMORY.md` (index) | yes | pointers to memory entries, not the entries themselves | | Memory entries | on demand | loaded when the agent decides they're relevant | | Skills | on demand | progressive disclosure — `SKILL.md` frontmatter triggers the load |