@owlmeans/create-app 0.1.16-rc.0 → 0.1.17

package/template/_github/instructions/memory-promotion.instructions.md

@@ -1,111 +0,0 @@
----
-description: "Promote procedure-shaped or hot memory into skills/instructions — triggers (procedure test, promote? flags, over-cap), the mandatory distillation rewrite, update-vs-create rule, post-promotion pointer state. Apply when converting memory content into guidance files or when a promote? flag appears in a memory node."
-applyTo: "**/.agents/memory/**, **/.claude/skills/**, **/.github/instructions/**"
-scope: general
----
-<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
-
-# Memory promotion
-
-Memory holds **facts**; **procedures** belong in instructions/skills, where they auto-apply and
-stop consuming memory-read cycles. Promotion is how the store stays compact and the harness
-teaches itself.
-
-Promotion is a **rewrite, never a move**. Memory text pasted into an instruction is the single
-most common way this harness degrades — see Distillation below.
-
-## Triggers
-
-- **Procedure shape**: the content answers *how to do X* — ordered steps, imperative verbs,
-  command lines, if-this-do-that tables. Promote it.
-- **Repeated touch**: an existing ` → promote?` flag on content you are touching again means
-  promote now; if mid-task, promotion becomes the first row of the completion report.
-- **Over-cap**: a node past the 120-line hard cap with roughly a third or more procedure-shaped
-  content → promote the procedures instead of splitting the node.
-- Corroborating only (weak — agents don't commit, so only user commits appear):
-  `git log --oneline -- .agents/memory/<node>.md` showing ≥ 3 commits within ~a month marks a
-  hot node worth evaluating.
-
-## Procedure-shape test
-
-Procedure-shaped answers *how to do X*: ordered steps, imperative verbs, commands, action tables.
-Fact-shaped answers *what is true*: declarative structure, invariants, symptom→cause pairs.
-Mixed entries split — the fact stays in the node, the "then do" is distilled into a rule in the
-instruction.
-
-## Distillation (mandatory)
-
-**Never paste memory text into an instruction.** A promoted line leaves the node as prose about a
-past occurrence and enters the instruction as **one general rule**: *when this applies → do this
-→ or this breaks*, stated so it holds next time rather than describing last time.
-
-| Strip | Keep |
-|---|---|
-| dates, phase/status markers, "COMPLETE", "landed" | the condition that makes the rule apply |
-| versions, image tags, SHAs — unless the rule turns on the version | the step to take |
-| "was X, now Y", "the former X was removed" | the failure it prevents |
-| who did it, attempt sequences, incident narrative | the recognition fingerprint (symptom) |
-| point-in-time inventories, counts, snapshots | |
-
-Before (memory): "2026-07-05 — the control-board git card was removed; the dialog now owns all
-git actions."
-After (rule): "Git actions live in the git dialog; the control board holds none."
-
-Before (memory): "Phase 3 (COMPLETE, 2026-06-13): added the init-container build, publisher
-`src/build.ts`, kephemeral v0.1.5."
-After (rule): "Production images build in an init container driven by `publisher/src/build.ts`."
-
-**If the rule cannot be stated without saying when it happened, it is not promotable** — it stays
-a memory fact, or it is dropped.
-
-### Budget
-
-A promotion normally adds **1–5 lines** to an existing instruction, and a single rule is ≤ 3 lines.
-A whole new section, or more text added than the node lost, means the content was moved rather than
-distilled — redo it.
-
-An instruction may legitimately run long when it maps a large subsystem, so length alone is not the
-test: **every line must be a rule, a contract, or a pointer.** A section that reads as the story of
-how the code got there is pollution at any length. "Record the rule, not the story"
-(`agent-memory.instructions.md`) binds instruction bodies at least as tightly as it binds nodes.
-
-## Flagging (how content earns promotion)
-
-When you **merge** procedure-shaped content into a node, or you **use** (not merely check) a
-node's content to perform a task, append ` → promote?` to that line or section heading.
-Evaluable by reading the file alone — no tooling required.
-
-## Update vs create
-
-**Default is update** — extend the existing instruction/skill whose scope covers the activity,
-even partially; keep both twins in sync. Create a NEW pair only when:
-
-- (a) a new subsystem or technology entered the repo;
-- (b) an activity with no covering instruction needed memory read/write more than once (a
-  re-encountered ` → promote?` flag);
-- (c) an external technology required internet docs and has no governing instruction.
-
-New instructions multiply lookup cost — compactness applies to the guidance population *and* to
-each instruction's body.
-
-## Procedure
-
-1. Collect the flagged / procedure-shaped memory lines.
-2. **Distill** each into a general rule (section above). Not optional — skipping it is the
-   failure mode this instruction exists to prevent.
-3. Author or extend the `.github/instructions/<name>.instructions.md` and its
-   `.claude/skills/<name>/SKILL.md` twin, following the repo's skill-authoring / create-skill
-   conventions. Where an existing rule already covers the ground, **rewrite that rule in place**;
-   append only when nothing covers it.
-4. Shrink the node: delete the source lines; leave one pointer line (format below).
-5. Remove the ` → promote?` flags.
-6. Update the node's index hook if its main value moved; bump `updated:`.
-7. Report per the Reporting rule.
-
-## Post-promotion state
-
-The node keeps exactly one line under `## Pointers`:
-
-```
-- <activity> → skill `<name>` (procedure lives in .claude/skills/<name>/ + .github/instructions/<name>.instructions.md)
-```

package/template/_github/instructions/memory-recompact.instructions.md

@@ -1,73 +0,0 @@
----
-description: "Whole-store memory recompaction and migration for .agents/memory/ — rebuild node map from project structure, merge records, enforce caps, regenerate the index, fold in and delete legacy .claude/memory and .github/memory stores. Apply when restructuring a memory store or migrating legacy stores."
-applyTo: "**/.agents/memory/**, **/.claude/memory/**, **/.github/memory/**"
-scope: general
----
-<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
-
-# Memory recompaction
-
-Whole-store maintenance for `.agents/memory/` (protocol:
-`.github/instructions/agent-memory.instructions.md`). Also the migration procedure for legacy
-`.claude/memory/` + `.github/memory/` stores. Store-wide rewrite — propose it when triggers
-appear; the operator invokes it.
-
-## When
-
-- An index entry runs longer than one line, or the index exceeds 50 lines.
-- Nodes keyed by event/date/phase/task, or bodies reading as session narratives.
-- The same fact stated in two or more nodes.
-- More than ~20% of a node is stale `Status` content.
-- A node's `updated:` is months behind commits touching its scope.
-- Legacy `.claude/memory/` or `.github/memory/` dirs exist → run the migration below.
-
-## Build the target node map first
-
-Before reading any record bodies, derive the node set from **project structure**: workspaces
-array / top-level dirs → subsystem nodes; then the cross-cutting concerns and external
-integrations actually present. Write the map down (old file/section → target node). Every
-existing record must land in exactly one node — or split into atoms landing in several. Only
-then process records.
-
-## Per-record pass
-
-For each old file or section:
-
-1. Apply the agent-memory extraction rule — keep invariants, cause→effect, counter-moves,
-   symptom fingerprints; drop narratives, dates, attempt logs, anything code/git already states.
-2. Route each surviving atom to its node's section (Facts / Invariants / Gotchas / Pointers;
-   genuinely in-flight state → `Status`, dated).
-3. On conflict between records, the version consistent with **current code** wins — check the
-   code, don't average.
-4. Procedure-shaped survivors do not enter nodes — route them to
-   `.github/instructions/memory-promotion.instructions.md`. Routing means distilling them into
-   general rules, never handing the text over verbatim.
-
-## Legacy-store merge (migration)
-
-1. Union `.claude/memory/` and `.github/memory/`. Same-named files are two drifted sources of
-   ONE node — merge both; the code-consistent version wins.
-2. Index-only entries with no backing file: extract the fact into its node, or drop if stale.
-3. Old `## Skills` / "Key Files" index sections are dropped — skills self-describe; harness
-   layout belongs to `CLAUDE.md` / `.github/copilot-instructions.md`. Move genuinely non-obvious
-   dispatch hints there.
-4. When the new store verifies (below), delete both legacy dirs entirely.
-
-## Regenerate the index
-
-Rebuild `MEMORY.md` from the resulting nodes per the agent-memory format — never edit the old
-index incrementally.
-
-## Verify
-
-- Every node file is listed in the index; every listed node exists; every wiki-link resolves.
-- All caps met (index ≤ 50 lines; nodes ≤ 120; entries ≤ 3 lines; Status ≤ 5 dated lines).
-- No dates outside `Status` and `updated:`; no event-keyed filenames.
-- Both root instruction files' Memory sections point at `.agents/memory/`.
-- Legacy dirs gone; `grep -rn '\.claude/memory\|\.github/memory'` over the repo's harness files
-  returns nothing but allowlisted historical mentions.
-
-## Report
-
-One table: **Node** | **Sources merged** | **Lines before → after**. Follow the Reporting rule
-(what, not why).

package/template/_github/instructions/reuse-code.instructions.md

@@ -1,50 +0,0 @@
----
-description: "Discovery-first, reuse-first workflow for OwlMeans projects. Apply before planning or building any feature, before proposing a third-party library or custom solution, and after writing code: find an existing @owlmeans/* package or existing code first, extend before writing new, and simplify what you write."
-applyTo: "**/*.ts, **/*.tsx, **/package.json"
-scope: general
----
-<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
-
-# Reuse before you build
-
-OwlMeans ships a large framework of `@owlmeans/*` packages. Before proposing a third-party library,
-designing a custom solution, or finishing a feature, exhaust what already exists. Apply these four
-steps in order — during planning **and** implementation.
-
-## 1. Find an `@owlmeans/*` package first
-
-- **Consult the deployed instructions.** Each installed `@owlmeans/*` package ships
-  `.github/instructions/<pkg>.instructions.md` (and `.claude/skills/<pkg>/SKILL.md`) describing what it
-  does — your local catalogue of installed capabilities.
-- **Scan installed packages** in `node_modules/@owlmeans/*` and, in a workspace, the nested
-  `sources/*/node_modules/@owlmeans/*`.
-- **Discover not-yet-installed packages** by researching the **owlmeans/common** repository — its
-  `tree.md` dependency map and per-package READMEs.
-
-### Local vs. web research (the symlink rule)
-
-- `ls -la node_modules/@owlmeans/<pkg>`: a **symlink escaping `node_modules`** — or a project whose own
-  workspace publishes `@owlmeans/*` packages (**this is the common repo**) — means the source is local.
-  **Research locally** (`tree.md`, the package sources, the canonical instructions); do **not** use the
-  internet.
-- Otherwise (clean npm install), **research the web**: https://github.com/owlmeans/common.
-
-After adding an `@owlmeans/*` dependency, run `npx @owlmeans/agent-skills` to deploy its instruction.
-Prefer an `@owlmeans/*` package over a third-party library or bespoke code.
-
-## 2. Reuse or extend before writing custom
-
-If an installed package nearly fits, configure or extend it (its resources, services, modules, helpers)
-rather than writing a parallel implementation.
-
-## 3. No package? Reuse code and extract an abstraction
-
-Search the codebase for code solving a **similar** problem. Factor out a shared helper or abstraction
-instead of duplicating or starting from scratch. Write new code only when nothing reusable exists.
-
-## 4. Simplify after writing
-
-Review new code: can it be shorter, clearer, fewer moving parts? Lean on framework utilities, drop dead
-branches. Less code that reuses the framework beats more bespoke code.
-
-See the `dependency-tree`, `scaffolding`, and `bun` instructions.

package/template/_github/instructions/self-education.instructions.md

@@ -1,85 +0,0 @@
----
-description: "Mandatory post-development skill/instruction updating — after adding or changing functionality, rewrite touched project guidance as current rules (never as change notes), note external-doc findings in the governing instruction, or add instructions for new subsystems/technologies; required before the completion report when development started from an agreed plan. Apply when editing skills or instruction files after development."
-applyTo: "**/.claude/skills/**, **/.github/instructions/**"
-scope: general
----
-<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
-
-# Self-education
-
-After functionality is added or changed, the guidance that describes it must catch up — the agent
-teaches itself for next time. This pass runs after implementation and verification, **before**
-the completion report.
-
-## When (mandatory)
-
-Development "started from planning" when the session produced a plan the operator approved before
-implementation — a plan approval, an agreed written plan/spec, or an explicit "go ahead" on a
-proposed approach. **Approval of a plan is simultaneously approval of its implicit final step:
-this self-education pass.** A planned task is not finishable without it. If guidance files cannot
-be edited (read-only run), list the required updates in the report instead.
-
-Also recommended after any unplanned change that made an existing instruction/skill inaccurate.
-
-## Review checklist
-
-For each area the work touched:
-
-1. Which existing instruction/skill covers it? (Check `.github/instructions/` +
-   `.claude/skills/`.)
-2. Do its commands, paths, APIs, and behavior claims still hold after the change?
-3. Fix in place — rewrite the affected lines so they describe current behavior; never append a
-   note about what this change did. Keep the instruction and its skill twin in sync.
-
-## Shape of an update
-
-Instructions and skills state **current rules, not what changed**. Every edit is a rewrite in
-place of the affected lines.
-
-Never write into an instruction or skill: dated bulletins ("2026-07-05 — …"), phase or migration
-status ("Phase 3 complete", "migration done", "landed"), "formerly X, now Y", incident
-narratives, fixed-bug logs, or point-in-time inventories. If a line only makes sense to someone
-who watched the change happen, it does not belong in guidance — the rule it taught does, stated
-timelessly. Facts too specific to generalize go to `.agents/memory/`
-(`.github/instructions/agent-memory.instructions.md`); the rewrite recipe is
-`.github/instructions/memory-promotion.instructions.md` → Distillation.
-
-Test: a finished instruction reads as though the feature was always this way.
-
-## Non-project instructions
-
-If a general or imported instruction gained an important usage pattern during the work, add the
-pattern to the **deployed copy** in this repo and note it in the report as an upstream
-candidate — canonical archive copies change only on explicit operator request.
-
-## External docs
-
-If the work required reading internet documentation for an external API, library, or service,
-the governing instruction must record it under an `## External docs` heading:
-
-```
-- <URL> — <one-line gist of what it settled> (<version/date if load-bearing>)
-```
-
-Governing instruction = the project instruction covering the touched area; else the one covering
-that library; if none exists and the technology will recur, create one (update-vs-create rule in
-`.github/instructions/memory-promotion.instructions.md`). Never leave doc findings only in
-memory or the conversation.
-
-## New subsystems / technologies
-
-When new technology or a new subsystem entered the repo: create the instruction/skill pair for
-its procedures, and/or the `.agents/memory/` node for its facts — split along the
-memory-vs-instruction boundary (`.github/instructions/agent-memory.instructions.md` /
-`.github/instructions/memory-promotion.instructions.md`).
-
-## Completion gate
-
-The completion report must contain a Self-education table:
-
-| Item | Action | Path |
-|---|---|---|
-| <area/skill> | updated / created / none-needed | <path> |
-
-"none-needed" requires a one-phrase reason. A post-plan completion report without this table is
-a protocol violation.

package/template/_github/instructions/skill-authoring.instructions.md

@@ -1,66 +0,0 @@
----
-description: "How to add agent guidance to an OwlMeans project — author a Claude Code skill (.claude/skills/<name>/SKILL.md) and the matching Copilot instruction (.github/instructions/<name>.instructions.md), keep them in sync, and choose skill vs memory. Apply when capturing knowledge as a skill or instruction."
-applyTo: "**/.claude/skills/**, **/.github/instructions/**"
-scope: general
----
-<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
-
-# Authoring agent guidance (skills + instructions)
-
-OwlMeans projects carry agent guidance in two parallel places so both Claude Code and GitHub
-Copilot can use it:
-
-| Tool | Location | Shape |
-|---|---|---|
-| Claude Code | `.claude/skills/<name>/SKILL.md` | one directory per skill, `SKILL.md` is the entrypoint |
-| GitHub Copilot | `.github/instructions/<name>.instructions.md` | one file per topic |
-
-Author **both** for any guidance you want available to either tool, using the same `<name>` on both
-sides so they read as one topic.
-
-## SKILL.md frontmatter (Claude Code)
-
-```yaml
----
-name: my-skill                  # the /slash-command (lowercase, hyphens)
-description: What it does and WHEN to use it.  # primary auto-invocation signal
-user-invocable: true            # false = background knowledge only
-allowed-tools: Bash(bun *) Read # optional
----
-```
-
-The `description` decides when Claude auto-invokes the skill — describe the topic and the trigger.
-
-## Instruction frontmatter (Copilot)
-
-```yaml
----
-description: "Short summary — apply when …"
-applyTo: "**/*.ts, **/relevant/**"   # globs that auto-attach this instruction
----
-```
-
-`applyTo` controls when Copilot attaches the instruction. Use the patterns the guidance is about;
-fall back to `**/*.ts, **/*.tsx` if broadly relevant.
-
-## Keep the pair in sync
-
-Change one side, change the other. They need not be identical prose but must not contradict.
-Cross-reference related guidance by name.
-
-## Skill vs memory
-
-- **Skill / instruction** — a reusable procedure or reference worth auto-invoking.
-- **Memory** (shared `.agents/memory/` graph store, both tools) — a fact, decision, or gotcha
-  specific to this project's history. See the agent-memory instruction; promotion triggers live
-  in the memory-promotion instruction.
-
-Never paste memory text into guidance. Memory content enters an instruction or skill only as a
-restated general rule — trigger, step, and the failure it prevents, with dates, phase/status
-markers, versions and incident narrative stripped (memory-promotion instruction → Distillation).
-
-## After adding a skill
-
-If it distilled memory content into rules, shrink the source `.agents/memory/` node to a pointer line
-(memory-promotion instruction) — the memory index does not list skills. Reference it from
-`.github/copilot-instructions.md` / `CLAUDE.md` if it should be discoverable every session.