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:

ls package.json pyproject.toml *.psd1 *.psm1 requirements.txt 2>/dev/null

Then survey:

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

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

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.