Skip to content

sprngr/rubber-duck / src/skills/duck-tape

duck-tape

Verified

Two-tier session memory: CONTEXT.md (persistent) + .duck-tape working state, with merge/dedupe. Subcommands: merge, resume, init, prune, migrate. Use when: "duck-tape", "compact session", "update CONTEXT.md", "resume session".

FileKindSize
README.mdmarkdown15.5 KB
SKILL.mdskill md14.4 KB
examples/CHANGELOG.mdmarkdown419 B
examples/CONTEXT.mdmarkdown2.1 KB
examples/STATE.mdmarkdown1.2 KB
examples/bootstrap-CONTEXT.mdmarkdown463 B
hooks/claude-code.hooks.jsonconfig291 B
hooks/claude-code.hooks.windows.jsonconfig312 B
hooks/copilot.hooks.jsonconfig325 B
hooks/extract-raw.ps1script15.2 KB
hooks/extract-raw.shexecutablescript12.2 KB
hooks/extract-state.ps1script15.1 KB
hooks/extract-state.shexecutablescript11.3 KB
hooks/opencode.plugin.jsscript12.9 KB
hooks/pre-compact.ps1script1.1 KB
hooks/pre-compact.shexecutablescript1.0 KB
references/HOOKS_GUIDE.mdmarkdown11.3 KB
references/OUTPUT_SCHEMA.mdmarkdown3.8 KB
references/SCHEMA.mdmarkdown7.0 KB
references/STATE_SCHEMA.mdmarkdown5.7 KB
# duck-tape: Session Memory Management πŸ¦†πŸ“Ό

Two-tier memory system for AI agent sessions. Tier 1 persists long-term context into `CONTEXT.md`. Tier 2 captures working session state into `.duck-tape/` for handoff between sessions.

## Why Two Tiers

Not every session deserves permanent context. State files capture the full picture for recovery. CONTEXT.md holds only what advances the project long-term.

**Tier 1 β€” `CONTEXT.md`** (persistent, repo-tracked)

- Long-term memory across sessions
- 7 fixed schema sections with deterministic merge rules
- Committed to version control
- Merged from state files only on explicit merge signals

**Tier 2 β€” `.duck-tape/<id>.state.md`** (working, not committed)

- Short-term session state
- Agent State schema with position tracking, decisions, facts
- Auto-ignored (`.gitignore` created automatically)
- Rotated after 10 files (auto dropped first, then recovered, then manual)
- Staging input for CONTEXT.md merges

## Commands

### `/duck-tape` β€” Save session state (default)

Writes session state file only. Does not touch CONTEXT.md.

**Use when:** checkpointing progress, saving work before switching tasks, capturing state for potential recovery.

### `/duck-tape merge` β€” Merge into CONTEXT.md

Writes session state file, then merges translated content into CONTEXT.md.

**Use when:** the session produced decisions, conventions, or facts that belong in long-term memory.

### `compact session` / `persist memory` / `update CONTEXT.md`

Alias for `/duck-tape merge`. Same behavior.

### `/duck-tape prune` β€” Cull Notes entries

Lists timestamped Notes entries in CONTEXT.md. You pick which to remove. If a target is a fixed-schema section, leave it untouched.

**Use when:** CONTEXT.md Notes section grows too large. Old observations that no longer matter.

### `/duck-tape migrate` β€” Restructure CONTEXT.md

Classifies freeform content in an existing CONTEXT.md into schema sections. Proposes the restructure before executing.

**Use when:** you have a CONTEXT.md that predates the schema or drifted from structure.

### `/duck-tape init` β€” Guided hook install

Prompts for harness choice (opencode, Claude Code, Copilot) and platform (unix/Windows for Claude Code). Writes the correct hook config snippet to the right path. Explains placement.

**Use when:** setting up pre-compact trigger for the first time. See `references/HOOKS_GUIDE.md` for manual install.

### `/duck-tape resume` β€” Reload from compaction

Checks `.duck-tape/.last-compact` marker. If compaction occurred this session, reads latest state file and CONTEXT.md. Reports position, decisions, and facts. If only an auto-checkpoint exists (no manual), invokes LLM-assisted recovery: reads transcript via `extract-raw.sh`/`.ps1`, synthesizes a higher-fidelity `-recovered.state.md` state file. State file write requires approval.

**Use when:** compaction may have occurred and you lost context. Signal: "resume session".

## Typical Workflow

Five scenarios covering the session lifecycle.

### First-time setup

1. Run `/duck-tape init`. Pick your harness (opencode, Claude Code, Copilot). Skill writes hook config to the right path.
2. Confirm `hooks/extract-state.sh` (unix) or `hooks/extract-state.ps1` (Windows) is in project. opencode skips this (JS plugin fetches via SDK).
3. Start working. Hook fires automatically on compaction. Writes `.duck-tape/.last-compact` marker and `.duck-tape/<id>-auto.state.md` state file with auto-extracted content (Approved Workflow, Position, Decision Log). Falls back to marker-only if jq missing (bash), transcript missing, or parse fails.

### During a session

1. Checkpoint after completing a logical unit of work: feature done, decision made, bug fixed.
2. Run `/duck-tape` or say "checkpoint session". Skill writes state file with position, decisions, facts.
3. Continue working. Repeat as needed. State files rotate (max 10, auto dropped first, then recovered, then manual).
4. No need to checkpoint mid-thought. State files capture where you are, not every keystroke.

### After compaction

1. If you notice missing detail or context feels summarized, compaction may have occurred.
2. Run `/duck-tape resume` or say "resume session". Skill checks `.duck-tape/.last-compact` marker.
3. If marker is newer than session start: compaction occurred. Skill selects state file by precedence: manual > recovered > auto.
4. If only an auto-checkpoint exists or no state file: skill invokes LLM-assisted recovery. Runs `extract-raw.sh`/`.ps1` on transcript (path from marker `transcript` field), reads raw material, synthesizes `<id>-recovered.state.md` with semantic decision extraction. State file write requires approval.
5. If manual checkpoint exists and is newer: skill reads it directly. No recovery needed.
6. Skill reads CONTEXT.md, reports position, decisions, facts. Pick up where you left off.

### End of a session

1. Ask: did this session produce decisions, conventions, or facts worth keeping long-term?
2. If yes: run `/duck-tape merge` or say "compact session". Skill writes state file, then merges translated content into CONTEXT.md. Changelog reports what changed.
3. If no: run `/duck-tape` for a state-only checkpoint. State file stays in `.duck-tape/` for recovery. CONTEXT.md untouched.
4. If CONTEXT.md does not exist yet: merge triggers bootstrap. Skill creates CONTEXT.md with scaffold from state file content.

### Periodic maintenance

1. Check CONTEXT.md Notes section size. If it grew large, run `/duck-tape prune`. Pick stale entries to remove. If an entry is in a fixed-schema section, leave it; prune Notes only.
2. Review Deferred-Debt entries. Update status markers as decisions get made.
3. If CONTEXT.md drifted from schema (freeform content outside the 7 sections), run `/duck-tape migrate`. Skill classifies content and proposes restructure.
4. Check `.duck-tape/` for old state files. Rotation handles this automatically (max 10), but verify if disk space matters.

## Context Hygiene

Good context hygiene keeps CONTEXT.md useful. Bad hygiene turns it into noise.

### When to merge

Merge into CONTEXT.md when the session produced:

- **Decisions** that constrain future work (architecture choices, API contracts, naming conventions)
- **Conventions** that other contributors need to follow
- **Glossary terms** that recur across sessions
- **Open questions** that block progress and need tracking
- **Deferred debt** with concrete revisit triggers

Skip merge when the session was:

- Exploratory research with no conclusions
- Debugging that resolved without lasting impact
- Conversational (teaching, explaining, brainstorming without decisions)
- Transient (fixing a typo, running a script, checking status)

### When to prune

Prune Notes entries when:

- The observation is stale (older decision superseded it)
- The detail is available elsewhere (code, docs, tickets)
- The entry is pure scratch-work (derivation steps you don't need to revisit)

If pruning, keep fixed-schema sections; those merge only.

### CONTEXT.md schema overview

```
## Goals           β€” What the project optimizes for
## Decisions       β€” Explicit choices made in session
## Conventions     β€” Project patterns and rules
## Glossary        β€” Domain terms and definitions
## Deferred-Debt   β€” Deferred work with status markers
## Open-Questions  β€” Unresolved questions
## Notes           β€” Freeform observations (append-only, prune-safe)
```

### Keeping CONTEXT.md small

- **One entry, one line.** Decisions and conventions are single-line keyed entries.
- **Supersede, don't accumulate.** When a decision changes, the old entry is replaced. The changelog records what changed.
- **Notes is the dump zone.** Freeform content goes here. Prune it when it stops being useful.
- **If Goals or Conventions lack an entry**, add only from explicit user decisions; do not infer.

### When CONTEXT.md should graduate to documented artifact

`CONTEXT.md` is project memory for continuity.  
It is not the long-term source of truth for team contracts.

Promote entries from `CONTEXT.md` into durable docs when they become stable, reusable, or safety-critical.

Graduate when any are true:

- **Repeated dependency:** the same decision gets reused across sessions or contributors.
- **Safety/authorization impact:** wrong interpretation can cause unsafe, unauthorized, or irreversible actions.
- **External contract impact:** behavior affects API, schema, config, CLI, or user-visible behavior.
- **Onboarding criticality:** new contributors must know this before changing code.
- **Low expected churn:** decision is unlikely to change in near-term execution.

Recommended destination:

- **Behavior rules and execution constraints** -> project agent policy document
- **Architecture decisions and tradeoffs** -> ADRs / architecture docs
- **Developer workflow conventions** -> contribution or engineering playbook docs
- **User/operator behavior** -> product README, runbooks, CLI docs
- **Unsettled or transient context** -> keep in `CONTEXT.md` (Open-Questions/Notes) until stable

Rule of thumb:

- If violating it can create unsafe or unauthorized behavior, make it normative in policy/docs.
- If it mainly prevents re-derivation between sessions, keep it in `CONTEXT.md`.

## Session State Schema

State files use the Agent State schema:

```
# Agent State

Session: <id> | Cwd: <path> | Repo/Branch: <repo>@<branch>
Created: <ISO-8601>

## Approved Workflow
<what was approved, link spec/plan/ticket>

## Position
- **Current:** <step in flight>
- **Done:** <ordered newest last>
- **Remaining:** <in order>

## Decision Log
<ISO-8601> APPROVED/REJECTED: <what> - <reasoning>

## Established Facts
<facts established during session>

## Re-derivation
<how to recover state: commands, files, endpoints>

## Suggested Skills
<optional, skills for next session>
```

The state file translates into CONTEXT.md via a rigid map:

- Approved Workflow + Decision Log β†’ **Decisions**
- Position.Remaining β†’ **Open-Questions**
- Established Facts β†’ **Glossary**
- Position.Current + Position.Done β†’ consumed by next agent, not merged (state-file-local)
- Re-derivation β†’ consumed by next agent, not merged
- Suggested Skills β†’ consumed by next agent, not merged

## Harness Integration

Pre-compact trigger writes `.duck-tape/.last-compact` marker and `.duck-tape/<id>-auto.state.md` state file before context compaction. State file is auto-extracted from the session transcript (Claude Code, Copilot) or fetched via SDK (opencode). Contains auto-extracted Approved Workflow, Position (tool calls + last assistant text), and Decision Log (pattern-matched). Low-fidelity recovery fallback β€” manual `/duck-tape` checkpoint produces higher-fidelity state.

Marker format: `<timestamp> | cwd: <path> | latest-state: <file> | transcript: <path>`. The `transcript` field records the source transcript path (Claude Code, Copilot) or opencode snapshot path (`<id>-transcript.json`). Absent in older markers written before Angle B, or when transcript was unavailable at compaction time.

**Fallback:** marker-only on failure. jq missing (bash), transcript missing, format unknown, nothing extracted, SDK error (opencode). `pre-compact.sh`/`.ps1` retained as marker-only fallback scripts.

**Resume from compaction:** triggered by `/duck-tape resume` or "resume session". Skill checks `.duck-tape/.last-compact`. If marker exists and is newer than session start, compaction occurred. State file precedence: manual > recovered > auto. If only auto-checkpoint or no state file exists, skill invokes LLM-assisted recovery (Angle B): runs `extract-raw.sh`/`.ps1` on transcript, synthesizes `<id>-recovered.state.md` with semantic decision extraction. Higher fidelity than auto, lower than manual. State file write requires approval. opencode plugin writes incremental `<id>-transcript.json` snapshot at pre-compact time (messages since last state file) for recovery input.

**Behavior identical across opencode, Claude Code, and Copilot.** No threshold detection. No context re-injection. State file + marker.

**Install:** run `/duck-tape init` for guided setup, or see `references/HOOKS_GUIDE.md` for manual install per harness.

## Security

Redaction runs before every write. Secrets, API keys, tokens, passwords, and PII are detected and blocked. If flagged content would reach persistent storage, confirm masking (`<REDACTED>`) with the user first.

Redaction applies to both tiers (CONTEXT.md and state files).

### Hook environment variables

Hook scripts support these controls:

- `DUCK_TAPE_MAX_TRANSCRIPT_BYTES`
  - Maximum transcript/snapshot size in bytes.
  - Default: `5242880` (5 MB).
- `DUCK_TAPE_TRUSTED_ROOT`
  - Optional root boundary for transcript path checks.
  - Default: unset (no root-boundary enforcement).
  - When set, transcript paths must resolve inside this root (or equal it), or hooks fall back safely.

Symlink rejection and size-cap checks remain active regardless of `DUCK_TAPE_TRUSTED_ROOT`.

Examples:

- Bash:
  - `export DUCK_TAPE_TRUSTED_ROOT="$PWD"`
  - `export DUCK_TAPE_MAX_TRANSCRIPT_BYTES=5242880`
- PowerShell:
  - `$env:DUCK_TAPE_TRUSTED_ROOT = (Get-Location).Path`
  - `$env:DUCK_TAPE_MAX_TRANSCRIPT_BYTES = "5242880"`

## Troubleshooting

**CONTEXT.md lacks schema sections.** Run `/duck-tape migrate` to classify existing content and append missing headers.

**State files accumulating.** Check rotation cap (max 10). Eviction precedence: auto dropped first (oldest auto), then recovered, then manual. Dropped IDs are noted in CONTEXT.md Notes as freeform rotation entries.

**Merge produced unexpected entries.** Check the changelog. Each addition, supersession, and drop is logged with a reason. Use `/duck-tape prune` to clean Notes if needed.

## File Layout

```
<project>/
  CONTEXT.md                    β€” Tier 1 persistent memory
  .duck-tape/
    .gitignore                  β€” `*` (auto-created)
    .last-compact               β€” pre-compact marker (harness-written)
    <YYYY-MM-DD-HHMM>.state.md          β€” Tier 2 working state (manual /duck-tape)
    <YYYY-MM-DD-HHMM>-auto.state.md     β€” Tier 2 auto-extracted state (pre-compact hook)
    <YYYY-MM-DD-HHMM>-recovered.state.md β€” Tier 2 LLM-synthesized state (resume recovery)
    <id>-transcript.json                β€” opencode message snapshot (Angle B recovery input)
```

## References

- `references/SCHEMA.md` β€” full CONTEXT.md schema definitions and merge rules
- `references/STATE_SCHEMA.md` β€” Agent State schema and translation map
- `references/OUTPUT_SCHEMA.md` β€” strict output specifications for all artifacts
- `references/HOOKS_GUIDE.md` β€” per-harness hook install, troubleshooting, portability notes
- `hooks/extract-state.sh` β€” pre-compact transcript parser (unix/bash, requires jq)
- `hooks/extract-state.ps1` β€” pre-compact transcript parser (Windows/PowerShell)
- `hooks/extract-raw.sh` β€” raw material extractor for LLM-assisted recovery (unix/bash, requires jq)
- `hooks/extract-raw.ps1` β€” raw material extractor for LLM-assisted recovery (Windows/PowerShell)
- `hooks/opencode.plugin.js` β€” opencode plugin (JS, SDK fetch, cross-platform, no shell)
- `hooks/pre-compact.sh` β€” marker-only fallback script (unix/bash)
- `hooks/pre-compact.ps1` β€” marker-only fallback script (Windows/PowerShell)
- `hooks/claude-code.hooks.json` β€” Claude Code hook config (unix)
- `hooks/claude-code.hooks.windows.json` β€” Claude Code hook config (Windows)
- `hooks/copilot.hooks.json` β€” Copilot hook config (unix + Windows fields)
- `examples/bootstrap-CONTEXT.md` β€” empty scaffold with markers for new CONTEXT.md files
- `examples/CONTEXT.md` β€” fully populated CONTEXT.md sample
- `examples/STATE.md` β€” sample session state file
- `examples/CHANGELOG.md` β€” changelog output examples
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 196kUpdated Claude CodeCodexVerifiedInstall