# Context Kit Scaffold

> Scaffold a portable, name-agnostic starter kit for the next project -- any stack (Node.js, Python, PowerShell, ops/admin) -- by mining this project's accumulated docs, conventions, runbooks, agent-testing harness, and engineering strategies into a generic template tree under docs/genericcontext/. Produces a generic CLAUDE.md, stack-appropriate standards, five canonical runbook templates with empty lessons stubs, a sandboxed agent-smoke harness (restricted tester plus independent judge), an unattended-testing permission allowlist, a PORTING cheat-sheet, and a lessons-from-source-project.md that anonymizes and merges the portable strategies. Use whenever the operator wants to carry a project's hard-won patterns into a new one, or says 'generate generic context', 'scaffold next project from this one', 'extract docs as a starter kit', 'create a project template', or 'produce a generic CLAUDE.md'. Skip if the project has fewer than ~5 shipped changes, or back up first if docs/genericcontext/ already exists.

- Skill: `wawoodwa/context-kit-scaffold` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add wawoodwa/context-kit-scaffold`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wawoodwa/context-kit-scaffold/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: wawoodwa (https://skillmd.com/u/wawoodwa)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wawoodwa/context-kit-scaffold

---


# Generate Generic Context Skill

Bootstrap the next project from this one's hard-won accumulated knowledge --
**whatever the stack** (Node.js, Python, PowerShell, an ops/administration kit,
etc.). Strips project-specific content (tool names, vendor APIs, entity/tenant
IDs, dependencies), keeps the structure, conventions, **procedures, and the
portable engineering + agent-harness strategies**. Output is a kit under
`docs/genericcontext/` ready to copy into a fresh project root.

> **Stack-agnostic by design.** This skill historically targeted Node.js, and
> Node.js remains the canonical example throughout. But the *structure*,
> *conventions*, and *cross-cutting strategies* port to any stack. Phase 1
> resolves the target stack profile; Phase 4 then keeps that stack's discipline
> instead of hardcoding Node.js. Treat every Node.js-specific mention below as an
> example to translate into the source project's actual stack.

---

## Conventions (governed by context-kit-steward)

> --- GOVERNED CONVENTIONS (source: context-kit-steward charter v1.0) ---
> Do not edit here. Change the charter in context-kit-steward and re-run it to
> re-sync; local edits to this block will be overwritten on the next sync.

This skill SEEDS the shared Context Kit conventions into every kit it generates (full
text + rationale in the context-kit-steward charter):

- **Seeds C1-C4 + C8** into generated stubs and CLAUDE.md: work-start dating with a
  `Last Updated` line; newest-first changelog / chronological history with
  insert-in-position; the concurrency rules (re-read, minimal insert, Version =
  on-disk + 1, one writer-of-record); `docs/sessions/<work-date>-<slug>/notes.md`;
  leading-underscore read-only dirs.
- **Encodes C6 (reference-don't-embed):** generated kits REFERENCE the global kit
  skills (context-kit-check, context-kit-capture, context-kit-split); never
  bundle copies.
- **Encodes C9 (skill-authoring limits):** any SKILL.md it scaffolds (e.g. the
  agent-smoke skill) has a YAML description under 1024 chars, no angle brackets,
  ASCII-only -- after placeholder substitution.
- **Aware C5 (entity vocabulary); follows C10 (no `rm`, move to Trash).**

---

## When to Use

- The current project has meaningful accumulated docs (>=5 shipped changes,
  >=1 substantive runbook, lessons files exist).
- The operator wants to start a new project (any stack) with this one's wisdom
  baked in from day one -- including its testing strategies and agent harness.
- Trigger phrases: "generate generic context", "scaffold next project", "extract
  docs as a starter kit", "create a project template", "produce a generic
  CLAUDE.md", "carry these strategies into a new project".

**Skip when:**
- The project is too new to have conventions worth porting.
- The operator wants a true blank slate. Use `/init` instead.
- `docs/genericcontext/` already exists with non-trivial content. Offer to back
  up (`docs/genericcontext.bak.YYYYMMDD/`) before overwriting.

---

## Core principle

Hard-won knowledge has two layers:

1. **Project-specific:** tool names, vendor APIs, tenant IDs, dependencies,
   business-domain terminology. Inseparable from the project; not portable.
2. **Generic / structural:** the doc-tree shape, naming conventions, the
   active/durable history split, runbook procedures, soft-gate vs schema-gate
   patterns, pure-helper extraction, retry rules, stdout discipline, contract
   tests -- **and the cross-cutting strategies** the project paid to learn:
   sandboxed agent-smoke testing, honest-failure design, declaration-vs-ground-
   truth reconciliation, documentation-as-ground-truth, shared-budget backoff,
   unattended-testing permissions, telemetry, the operating model. **These port.**

The skill extracts layer 2, strips layer 1, produces a portable kit. The
operator copies it into a fresh project, runs find/replace on placeholders, and
ships -- already structured for the active/durable split (so the new project never
re-accumulates the bloat that triggered `/context-kit-split` here) and already
carrying the proven strategies as working scaffolding, not just prose.

### The kit's verifier is referenced, not embedded

The generated kit is designed to be audited by the **global `context-kit-check`
skill** -- the read-only auditor that checks Version/changelog coherence, changelog
ordering, link resolution, the `sessions/<date>-<slug>/notes.md` convention, and
date plausibility. Do **NOT** copy that skill into the generated kit. It is
project-agnostic and belongs installed once, globally; an embedded copy would
freeze at scaffold-time and drift from the canonical one. Instead, this skill
**bakes in the conventions that checker verifies** (so a fresh kit passes it) and
**points to it** from PORTING.md and the runbooks. The same applies to
`context-kit-capture` and `context-kit-split`: reference the global skills; never
bundle them.

**Lesson accumulation compounds across generations.** When the skill first ran on
a source project it produced `lessons-from-source-project.md` from that project's
lessons. That file lands at the new project's
`docs/_reference/lessons-from-source-project.md`. When the skill runs AGAIN on
that next project, it MERGES the inherited file with newly-extracted lessons -- so
wisdom compounds (Phase 8).

---

## Reference files (read these during the matching phase)

This SKILL.md is the workflow spine. The detail lives in `references/`:

| Reference | Read during | Holds |
|---|---|---|
| `references/strategies-catalog.md` | Phases 7 + new-artifact scaffolding | **The harvest.** 15 portable strategies: principle / why / portable shape / what to strip / where each lands in the kit. The checklist that stops a real strategy being DROPped for sounding project-specific. |
| `references/strategy-artifacts.md` | Phase 5b (strategy artifacts) | Ready-to-customize generic templates for the `.claude/` harness (settings allowlist, sandbox tester + judge agents, agent-smoke skill) and the `_tools/` snapshot note. |
| `references/lesson-extraction.md` | Phase 7 | The KEEP/DROP/ANONYMIZE heuristic with EXPANDED categories, the draft-table review, the lessons-file structure, and the inherited-lessons merge. |
| `references/runbook-templates.md` | Phase 5 | The five canonical runbooks + per-runbook keep/strip guidance + the companion `*-lessons.md` stub shape. |
| `references/generated-file-templates.md` | Phases 3, 4, 6 | The generic CLAUDE.md template, the standards.md extraction guidance, and the empty companion stubs (changelog, history, READMEs). |

---

## Output structure

```
docs/genericcontext/
|-- README.md                          # what this kit is + generated-from header
|-- PORTING.md                         # copy + customize cheat-sheet (incl. dotfile-copy gotcha)
|-- CLAUDE.md                          # generic entry-point, <INITIAL_VERSION> baseline
|-- .claude/                           # agent harness (scaffold the artifacts the source project exercised)
|   |-- settings.json                  # unattended-testing permission allowlist (strategy-artifacts #1)
|   |-- agents/
|   |   |-- surface-tester.md          # sandboxed restricted-tool agent-smoke executor (#2)
|   |   `-- surface-judge.md           # independent no-tool scorer (#3)
|   `-- skills/
|       `-- <surface>-agent-smoke/SKILL.md   # agent-smoke orchestration (#4) + catalog/fixture stubs
|-- _tools/
|   `-- README.md                      # isolated-tooling pattern + doc-snapshot note (#5)
`-- docs/
    |-- architecture.md                # generic architecture template
    |-- architecture/modules.md        # per-module deep-dive stub
    |-- changelog.md                   # empty changelog (header + "first row" comment)
    |-- history.md                     # empty history (header + summary-table stub)
    |-- standards.md                   # generic stack-appropriate standards (per Phase 4)
    |-- status.md                      # template with placeholder Project Context
    |-- project-team.md                # operating model (architect owns mapping; sub-agent roles; model policy)
    |-- runbooks/
    |   |-- extension-workflow.md            (+ -lessons.md)
    |   |-- audit-hardening-pass.md          (+ -lessons.md)
    |   |-- sub-agent-regression.md          (+ -lessons.md)
    |   |-- registry-reconciliation.md       (+ -lessons.md)
    |   `-- proposals-walkthrough.md
    |-- reviews/README.md
    |-- plans/README.md
    `-- _reference/
        |-- README.md
        `-- lessons-from-source-project.md   # accumulated portable lessons
```

The internal `docs/genericcontext/docs/` mirrors a real project's `docs/`, and
the `.claude/` + `_tools/` trees mirror a real project root -- so the operator can
copy the whole thing verbatim. **The `.claude/` and `_tools/` artifacts are
optional:** scaffold the ones whose strategy the source project actually
exercised (grep for them); leave the rest documented in PORTING.md as a menu.

---

## Placeholder conventions

Project-specific blanks use grep-friendly angle-bracket placeholders:

| Placeholder | Replace with |
|---|---|
| `<PROJECT_NAME>` | The new project's name (e.g., `stripe-mcp`) |
| `<PROJECT_TAGLINE>` | One-line description |
| `<PRIMARY_DEPENDENCY>` | Main runtime dep (e.g., `@modelcontextprotocol/sdk`, `stripe`) |
| `<API_VENDOR>` | Backing API/service |
| `<TOOL_PREFIX>` | MCP tool naming prefix (e.g., `stripe_`) |
| `<SURFACE>` | The tool-surface name used in the agent-smoke harness |
| `<ENTITY_OR_ACCOUNT_ID>` | Test environment identifier (tenant / account / customer / client) |
| `<ROLE_DESCRIPTION>` | Role & Identity for CLAUDE.md |
| `<INITIAL_VERSION>` | Starting version (default `1.0`) |
| `<OPERATOR_NAME>` | Maintainer name in doc footers |

PORTING.md documents the full list + a one-shot `sed` template. The skill does
NOT find/replace source content before generating -- the kit is a clean template;
the operator substitutes after copying.

---

## Workflow

### Phase 1: Confirm + survey
Ask the operator (don't skip -- placeholders need their plan): **target stack
profile** (Node.js / Python / PowerShell / ops-administration / other -- this
drives standards.md in Phase 4 and the permission-allowlist commands in Phase
5b)? dominant vendor/API? tool prefix? primary dependency? which strategies did
this project actually exercise (agent-smoke? doc snapshots? a permission
allowlist? a reconciliation pass?)? target project shape (MCP server / Lambda /
CLI / library / automation kit)? Does `docs/genericcontext/` exist (offer
backup)?

**Resolve the stack profile explicitly** -- it is the input that makes this skill
stack-agnostic. If the source project is not Node.js, you will translate the
Node.js examples in Phase 4 and the artifacts into that stack's equivalents
(e.g. PowerShell: modules + `Pester` tests + `Write-Verbose`/stream discipline;
Python: packages + `pytest` + `logging`; ops-admin: scripts + idempotency +
change-control). Survey for the stack signal:
```sh
ls package.json pyproject.toml *.psd1 *.psm1 requirements.txt 2>/dev/null
```

Then survey:
```sh
find . -name "*.md" -not -path "./node_modules/*" -not -path "*/_reference/*" \
  | xargs wc -l | sort -rn | head -20
ls docs/_reference/lessons-from-source-project.md 2>/dev/null && echo "EXISTS - will merge"
ls -d .claude/agents .claude/skills _tools 2>/dev/null    # which strategy artifacts exist to harvest
```

### Phase 2: Scaffold output directory
```sh
mkdir -p docs/genericcontext/docs/{architecture,runbooks,reviews,plans,_reference}
mkdir -p docs/genericcontext/.claude/{agents,skills} docs/genericcontext/_tools
```
If `docs/genericcontext/` existed and the operator approved a backup, `mv` it to
`docs/genericcontext.bak.$(date +%Y%m%d_%H%M%S)` first.

### Phase 3: Generate generic CLAUDE.md
Follow the template in `references/generated-file-templates.md`. Version starts at
`<INITIAL_VERSION>` (default `1.0`), NOT the source's current version. Keep
placeholders intact.

### Phase 4: Generate generic docs/standards.md
Copy the source `standards.md`; strip business-domain examples and vendor SDK
names; keep **the source stack's** runtime/IO/HTTP/logging/testing discipline
(from the Phase 1 stack profile). Node.js is the canonical example in
`references/generated-file-templates.md`; if the source is another stack, keep
the *equivalent* discipline rather than the Node.js specifics:
- **Node.js:** `.mjs`/ESM, `node:*` built-ins, `httpsRequest` wrapper, the log
  accumulator, stdout discipline (see the reference).
- **Python:** package layout, `pytest`, `logging` (not `print`), `requests`/
  `httpx` session reuse, type hints, venv isolation.
- **PowerShell:** advanced functions + modules (`.psm1`/`.psd1`), `Pester`
  tests, stream discipline (`Write-Verbose`/`Write-Error`, not host writes),
  `-WhatIf`/`-Confirm` on destructive cmdlets, idempotency.
- **Ops/administration:** idempotent scripts, change-control + rollback notes,
  least-privilege, dry-run-before-apply.

The cross-cutting items in the reference (the Standard Retry Pattern + its
shared-credential override forward note for strategy #7, the layered Testing &
Validation order, pure-helper extraction, the Rejected-Approaches table) are
**stack-independent** -- keep them whatever the stack, translating only the syntax.

### Phase 5: Generate the five runbook templates + lessons stubs
Per `references/runbook-templates.md`: extension-workflow, audit-hardening-pass,
sub-agent-regression, **registry-reconciliation** (the 5th -- the original kit
lacked it), and proposals-walkthrough. Each keeps the procedure, strips
specifics, and gets a companion `*-lessons.md` stub.

### Phase 5b: Scaffold the strategy artifacts (NEW)
For each strategy the source project exercised, emit its generic artifact per
`references/strategy-artifacts.md`: the `.claude/settings.json` allowlist; the
`surface-tester.md` + `surface-judge.md` sandbox agents; the
`<surface>-agent-smoke/SKILL.md` + catalog/fixture stubs; the `_tools/README.md`
isolated-tooling note (and a generic snapshot skill if the source shipped one);
`docs/project-team.md` (operating model). Mark each clearly optional. If the
source did NOT exercise a strategy, still leave the generic template as a menu
item but say so in PORTING.md -- don't fabricate evidence it was used.

### Phase 6: Generate empty companion stubs
`changelog.md`, `history.md`, the `reviews/`, `plans/`, `_reference/` READMEs, and
the `status.md`/`architecture.md`/`modules.md` scaffolds, per
`references/generated-file-templates.md`. Each stub carries a clear "first X goes
here" comment so the empty state doesn't read as a broken file.

**Seed the shared dating + concurrency conventions into the stubs** (per
`references/generated-file-templates.md`) so the new project starts disciplined and
passes the global `context-kit-check` from day one:
- **Dating:** every recorded date is the date the *work/conversation started*, not
  the wall-clock time the entry is written, formatted `YYYY-MM-DD`. CLAUDE.md and
  status.md carry a `Last Updated` line.
- **Ordering:** `changelog.md` and the `status.md` recent-changes table are
  newest-first; `history.md` is chronological. Insert each row in its correct date
  position, not blindly at the top.
- **Concurrency (multi-session/multi-agent):** before editing a shared index file,
  re-read from disk, make a minimal targeted insert (never a blind full rewrite),
  derive the new Version from on-disk + 1, and use one writer-of-record when
  several sessions/agents share the kit.

### Phase 7: Extract broadly-applicable lessons
The load-bearing phase. Per `references/lesson-extraction.md` and the checklist in
`references/strategies-catalog.md`: read the lessons files + CLAUDE/status/
architecture gotchas + the `.claude/`/`_tools/` evidence; classify each lesson
KEEP / DROP / ANONYMIZE using the expanded categories (which explicitly cover the
new strategies, so a real agent-testing/backoff/reconciliation lesson is not
DROPped for sounding project-specific).

### Phase 7a: Show the extraction draft to the operator
Present the classification as a table; let the operator approve or flip rows.
`AskUserQuestion` only for <10 ambiguous calls; otherwise show the table and take
plain-text edits. This 60-second review is what keeps the lessons file honest.

### Phase 7b: Write lessons-from-source-project.md
Write the KEEP + anonymized lessons grouped by theme, with provenance, per
`references/lesson-extraction.md`.

### Phase 8: Merge with inherited lessons (if applicable)
If the source had its own `docs/_reference/lessons-from-source-project.md`, merge
(heuristic dedupe; surface near-duplicates to the operator; preserve every
generation's section, newest last) per `references/lesson-extraction.md`.

### Phase 9: Generate PORTING.md
Cover: the copy step (note the **dotfile-copy gotcha** --
`cp -R docs/genericcontext/. /path/to/new-project/` so `.claude/` comes along, or
copy it explicitly); the full placeholder table + a one-shot `sed` template;
first-version bump (`1.0` + first changelog row); the customization checklist
(populate Project Context, Project Task Files, Resources; add the product's read
tools to `.claude/settings.json`; fill the agent-smoke `catalog.json`); what NOT
to do (don't customize the runbook procedures or strategy artifacts without a
real reason -- they encode hard-won patterns); how the lesson-accumulation merge
works on the next generation. **Also state the verifier dependency:** this kit is
designed to be audited by the GLOBAL `context-kit-check` skill (run it at
session start and before each end-of-chat capture); it is intentionally NOT
bundled -- install it from Settings > Capabilities if it is not already available,
and likewise for `context-kit-capture` and `context-kit-split`.

### Phase 10: Generate README.md for the kit
What this directory is (a portable starter kit, not part of the containing
project's runtime docs); one-paragraph quick start; link to PORTING.md; a
generated-from header (source project + date).

### Phase 11: Verify + report
```sh
find docs/genericcontext -type f | sort
grep -rn "<TBD\|<FIXME" docs/genericcontext && echo "UNRESOLVED MARKERS" || echo "clean"
```
Report: all expected files present; lesson counts (KEEP / ANONYMIZE / DROP, plus
merged-with-inherited if applicable); which strategy artifacts were scaffolded vs
left as menu items; any unresolved markers (should be zero).

Optionally **dogfood the global `context-kit-check` skill** against the
generated tree to confirm the structure, links, and ordering cohere. Expect
advisory WARNs for the intact `<PLACEHOLDER>` tokens and the empty stubs -- that is
correct for a template. There should be no FAILs (broken links, version/changelog
mismatch, out-of-order rows). If the checker is not installed, note it in the
report rather than fabricating a pass.

---

## Common pitfalls

1. **Over-stripping a strategy because it mentions a tool.** "Sandboxed agent-
   smoke" or "stdout discipline in MCP servers" *sound* project-specific, but the
   PATTERN ports cleanly to any agent-facing tool. ANONYMIZE the tool names; keep
   the pattern. `references/strategies-catalog.md` is the guard against this.
2. **Forgetting to strip vendor names.** A vendor name in a generic-sounding
   lesson doesn't port. Strip aggressively; the operator re-adds specifics.
3. **Skipping the strategy artifacts (Phase 5b).** The highest-value harvest is
   shipping the agent-smoke harness + permission allowlist as working scaffolding,
   not just describing them in a lessons file. Scaffold what the source used.
4. **The dotfile-copy gotcha.** `cp -r docs/genericcontext/*` silently drops
   `.claude/`. PORTING.md must use the trailing-dot form or copy `.claude`
   explicitly, or the whole agent harness is lost on copy.
5. **Pre-filling placeholders.** The generated CLAUDE.md must keep
   `<PROJECT_NAME>` etc. intact; the operator runs find/replace after copying.
6. **Inheriting the source's version.** The generated CLAUDE.md starts at `1.0`,
   not the source's current version.
7. **Skipping operator review of lesson extraction (Phase 7a).** The heuristic
   catches obvious cases; the 60-second review catches the rest.
8. **Re-running over an existing kit.** Always offer a backup first -- the operator
   may have hand-edited it.
9. **Lesson dedupe collapsing distinct lessons.** Same framing isn't always the
   same lesson; surface near-duplicates to the operator (Phase 8).
10. **Empty stubs that look broken.** Every stub needs a "first X goes here"
    comment explaining the empty state.
11. **Embedding a global skill into the kit.** Do not copy `context-kit-check`,
    `context-kit-capture`, or `context-kit-split` into the generated kit. They are
    project-agnostic and belong installed globally; an embedded copy goes stale.
    Reference them from PORTING.md; bake in the conventions they expect instead.
12. **A generated SKILL.md description that won't install.** The agent-smoke
    `SKILL.md` this kit scaffolds (and any other skill it emits) has a YAML
    `description`. After the operator substitutes placeholders it must contain **no
    angle brackets** (`<...>` reads as an XML tag and blocks "Save skill") and stay
    **under 1024 characters**. Keep `<SURFACE>`-style placeholders out of the final
    description, and say so in PORTING.md next to the substitution step.
13. **Hardcoding Node.js for a non-Node project.** standards.md, the allowlist
    commands, and the test-runner references must follow the Phase 1 stack profile.
    A PowerShell or admin kit that ships `npm test` allowlist entries and `.mjs`
    standards is wrong on arrival. Translate, don't transplant.
14. **Seeding wall-clock dates or top-of-file inserts.** The generated stubs must
    teach date = work/conversation start (not "today") and chronological insertion,
    or the new project inherits the exact dating/ordering bugs the global checker
    now flags.

---

## Checklist (end-of-skill)

- [ ] Stack profile resolved in Phase 1 (Node.js / Python / PowerShell / ops / other)
- [ ] `docs/genericcontext/` created (backed up first if it existed)
- [ ] Full tree generated per "Output structure"
- [ ] `CLAUDE.md` follows the generic template; placeholders intact; version `1.0`;
      carries a `Last Updated` line
- [ ] `docs/standards.md` strips business specifics, keeps the **stack profile's**
      discipline (not hardcoded Node.js) + the backoff-override forward note
- [ ] All five runbook templates + companion `*-lessons.md` stubs produced
      (including registry-reconciliation)
- [ ] Strategy artifacts scaffolded for every strategy the source exercised
      (`.claude/settings.json`, sandbox agents, agent-smoke skill, `_tools/` note,
      `project-team.md`); the rest documented as a menu in PORTING.md
- [ ] `changelog.md` / `history.md` empty tables + "first X" comments
- [ ] `lessons-from-source-project.md` = operator-approved KEEP + ANONYMIZE,
      grouped by theme, with provenance
- [ ] If inherited lessons existed: merged, all generations' sections present
- [ ] `changelog.md`/`history.md`/`status.md` stubs seed the dating + ordering +
      concurrency conventions (work-start dates, newest-first, re-read-then-insert)
- [ ] Global `context-kit-check` (and context-kit-capture / context-kit-split)
      **referenced** in PORTING.md, NOT embedded in the kit
- [ ] Any generated `SKILL.md` description is bracket-free and < 1024 chars after
      placeholder substitution (note this in PORTING.md)
- [ ] `PORTING.md` with full placeholder table + `sed` template + dotfile-copy
      gotcha + lesson-accumulation explanation + verifier-dependency note
- [ ] `README.md` naming the source project + mining date
- [ ] No unresolved `<TBD>` / `<FIXME>` markers
- [ ] Operator reviewed the extraction draft (7a) and any near-duplicate flags (8)

---

## Notes for autonomous loops

- Phases 1, 7a, and 8 (operator confirmations) are non-skippable. In `/loop`
  autonomous mode, stop at the first confirmation point and surface the question.
- Do not chain "now run on the next project" without explicit operator request.
- Do not delete `docs/genericcontext/` from the source after generating -- it's the
  operator's reference and may be needed for re-runs.