codebeltnet · gimlichael · May 3, 2026 · May 3, 2026 · May 3, 2026 · May 3, 2026
diff --git a/.gitignore b/.gitignore
@@ -15,3 +15,6 @@ skills/*-workspace/
 **/outputs/
 **/timing.json
 **/grades.json
+
+# Bot workspace (local-only AI agent ideation, PRDs, and agentic loop state)
+.bot/*
diff --git a/AGENTS.md b/AGENTS.md
@@ -282,3 +282,63 @@ Debug triggering: ask Claude `"When would you use the [skill name] skill?"` —
 | Instructions not followed | Too verbose or ambiguous | Shorten, use bullets, move detail to `references/` |
 | Slow / degraded responses | Too much content loaded | Keep SKILL.md under 5k words, use progressive disclosure |
 
+## Karpathy Rules
+
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+### 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+- When the root cause is uncertain, do not present hypotheses as facts. State the uncertainty explicitly and ask whether to investigate before applying a fix.
+
+### 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+### 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+### 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-05-03
+
+This is a minor release focused on deterministic repository story generation and foundational agent guidelines. It introduces a new `git-story-teller` skill with a bundled .NET context extractor, enhanced bot workspace management, and Karpathy programming principles for LLM agents.
+
+### Added
+
+- `git-story-teller` skill that reads a repository URL and generates a deterministic story overview and per-package target stories from grounded evidence,
+- Bundled C# context packer (`scripts/story.cs`) that clones repositories, discovers package targets, extracts grounded evidence via Repomix, and stages deterministic fixtures for story generation,
+- Karpathy rules in `AGENTS.md` for LLM-driven coding: think before implementing, favor simplicity, make surgical changes, and execute goal-driven with clear verification criteria,
+- `.bot/` workspace pattern to `.gitignore` for local agentic workspaces and ephemeral state.
+
+### Changed
+
+- Updated README to document `git-story-teller` installation, usage, and bundled C# runner approach,
+- Implemented Repomix web API and .NET packer fallbacks in `git-story-teller` for robust context extraction when network or CLI tools are unavailable.
+
 ## [0.3.4] - 2026-04-24
 
 This is a patch release that hardens the .NET scaffold guidance around hidden asset recovery and makes `git-keep-a-changelog` safer in yolo/auto mode. Incomplete `npx skills add` installs now pivot immediately to an upstream restore path driven by the shared asset manifest, while the changelog skill treats yolo/auto as an explicit full-autonomy mode instead of asking for scope confirmation.
@@ -141,7 +157,8 @@ This is a minor release that introduces two complementary git workflow skills, e
 
 - Improved scaffold fidelity with hidden `.bot` asset preservation, explicit UTF-8 and BOM handling, and checks aimed at preventing mojibake or incomplete generated output.
 
-[Unreleased]: https://github.com/codebeltnet/agentic/compare/v0.3.4...HEAD
+[Unreleased]: https://github.com/codebeltnet/agentic/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/codebeltnet/agentic/compare/v0.3.4...v0.4.0
 [0.3.4]: https://github.com/codebeltnet/agentic/compare/v0.3.3...v0.3.4
 [0.3.3]: https://github.com/codebeltnet/agentic/compare/v0.3.2...v0.3.3
 [0.3.2]: https://github.com/codebeltnet/agentic/compare/v0.3.1...v0.3.2

diff --git a/README.md b/README.md
@@ -54,6 +54,7 @@ npx skills add https://github.com/codebeltnet/agentic --skill git-nuget-readme
 npx skills add https://github.com/codebeltnet/agentic --skill git-visual-squash-summary
 npx skills add https://github.com/codebeltnet/agentic --skill skill-creator-agnostic
 npx skills add https://github.com/codebeltnet/agentic --skill markdown-illustrator
+npx skills add https://github.com/codebeltnet/agentic --skill git-story-teller
 npx skills add https://github.com/codebeltnet/agentic --skill trunk-first-repo
 npx skills add https://github.com/codebeltnet/agentic --skill dotnet-strong-name-signing
 npx skills add https://github.com/codebeltnet/agentic --skill dotnet-new-app-slnx
@@ -82,7 +83,8 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-new-lib-sln
 | [git-nuget-readme](skills/git-nuget-readme/SKILL.md) | Git-aware NuGet README companion for .NET repos that advertise a package from `src/`. Resolves the real packable project the README should sell, combines git history with actual package metadata, source capabilities, and relevant tests when feasible, preserves honest badge/docs/contributing sections, and writes a forthcoming, adoption-friendly `README.md` with repo-derived branding, clear value, install, framework-support, and quick-start guidance. |
 | [git-visual-squash-summary](skills/git-visual-squash-summary/SKILL.md) | Non-mutating grouped-summary companion to `git-visual-commits`. Turns the full current feature branch into a curated set of compact summary lines for PR or squash-and-merge contexts by default, preserving technical identifiers, merging overlap, dropping low-signal noise, highlighting distinct meaningful efforts, and avoiding changelog-style wording, unsupported claims, needless commit-range questions, or commit-selection UI for ordinary branch-level squash requests. |
 | [skill-creator-agnostic](skills/skill-creator-agnostic/SKILL.md) | Runner-agnostic overlay for Anthropic `skill-creator`. Adds repo and environment guardrails for skill authoring and benchmarking: temp-workspace isolation, `iteration-N/eval-name/{config}/run-N/` benchmark layout, valid `grading.json` summaries, generated `benchmark.json`, honest `MEASURED` vs `SIMULATED` labeling, and sync/README discipline for repo-managed skills. |
-| [markdown-illustrator](skills/markdown-illustrator/SKILL.md) | Reads a markdown file and answers directly in chat with one document-wide Visual Brief plus one compiled prompt. Infers a compact visual strategy by default, keeps follow-up questions near zero, and only branches when the user explicitly asks for added specificity. |
+| [markdown-illustrator](skills/markdown-illustrator/SKILL.md) | Reads a markdown file and answers directly in chat with one document-wide Visual Brief plus one compiled prompt. Infers a compact visual strategy by default, keeps follow-up questions near zero, and only branches when the user explicitly asks for added specificity. |
+| [git-story-teller](skills/git-story-teller/SKILL.md) | Turns any full repository URL into a deterministic story workspace using the bundled .NET file-based runner `scripts/story.cs`. Requires explicit `--repo-url` and `--output-root`, derives `{repo-id}`, fixes `result/`, packs context with local Repomix when available, the public Repomix web API for GitHub URLs when Node/npm is unavailable, or a lower-fidelity built-in .NET fallback as the last resort, writes target contexts plus manifest instructions, then guides the agent to write target stories before `result/Index.md` with a package-facing `## Package selection` overview section. |
 | [dotnet-new-lib-slnx](skills/dotnet-new-lib-slnx/SKILL.md) | Scaffold a new .NET NuGet library solution following codebeltnet engineering conventions. Dynamic defaults for TFM/repository metadata, latest-stable NuGet package resolution, tuning projects plus a tooling-based benchmark runner, TFM-aware test environments, strong-name signing, NuGet packaging, DocFX documentation, CI/CD pipeline, and code quality tooling. |
 | [dotnet-new-app-slnx](skills/dotnet-new-app-slnx/SKILL.md) | Scaffold a new .NET standalone application solution following codebeltnet engineering conventions. Supports Console, Web, and Worker host families with Startup or Minimal hosting patterns; Web expands into Empty Web, Web API, MVC, or Web App / Razor, plus functional tests and a simplified CI pipeline. |
 | [trunk-first-repo](skills/trunk-first-repo/SKILL.md) | Initialize a git repository following [scaled trunk-based development](https://trunkbaseddevelopment.com/#scaled-trunk-based-development). Seeds an empty `main` branch and creates a versioned feature branch (`v0.1.0/init`), enforcing a PR-first workflow where content only reaches main through peer-reviewed pull requests. |
@@ -128,10 +130,16 @@ npx skills add https://github.com/codebeltnet/agentic --skill git-visual-squash-
 npx skills add https://github.com/codebeltnet/agentic --skill skill-creator-agnostic
 ```
 
-`markdown-illustrator`
-
-```bash
-npx skills add https://github.com/codebeltnet/agentic --skill markdown-illustrator
+`markdown-illustrator`
+
+```bash
+npx skills add https://github.com/codebeltnet/agentic --skill markdown-illustrator
+```
+
+`git-story-teller`
+
+```bash
+npx skills add https://github.com/codebeltnet/agentic --skill git-story-teller
 ```
 
 `dotnet-new-lib-slnx`
@@ -273,6 +281,23 @@ Anthropic's `skill-creator` is an excellent base workflow, but the day-to-day fr
 - **Codex-friendly benchmarking** — treats Codex CLI as a valid real runner when present, preserves `MEASURED` parity honestly, uses raw event output as fallback evidence when convenience files are missing, and prefers parallel paired runs when the runner supports sub-agents
 - **Repo-managed discipline** — keeps per-skill evals, local-install sync, and README updates in scope for first-party skills
 
+### Why git-story-teller?
+
+Repository story generation works best when deterministic context gathering is separated from AI-authored prose. **git-story-teller** owns that split: its bundled .NET file-based runner creates the manifest, instructions, and one context file per target; the agent writes the target stories and overview.
+
+- **Bundled C# runner** - ships `scripts/story.cs`, run with `dotnet run --file`, so the skill is self-contained without a full project file
+- **Repomix-first packing** - uses `npx repomix` for the canonical XML context, ignore handling, token metadata, and security checks when Node/npm access is available
+- **Web API fallback** - if local Repomix cannot start and the input is a public GitHub HTTPS URL, posts the same pack request shape used by `https://repomix.com/` to the public Repomix API
+- **Local fallback path** - if both Repomix paths are unavailable, uses a simple built-in .NET text packer so public/non-sensitive story work can still proceed
+- **Repository-generic input** - starts from a full repository URL and an explicit output root instead of assuming an owner/slug convention
+- **KISS contract** - only `--repo-url` and `--output-root` are inputs; `{repo-id}` is derived and `result/` is fixed
+- **Codebelt-flavored default** - recommends `.bot/stories` when the active workspace already contains a `.bot` folder
+- **Tool output is authoritative** - reads `manifest.json`, `instructions.md`, and one target context at a time instead of reconstructing scope from memory
+- **Target-first workflow** - writes `result/{TargetName}.md` files before synthesizing `result/Index.md`
+- **Package-facing overview** - requires `result/Index.md` to use `## Package selection` for the reader-facing selection section
+- **Context-budget aware** - processes target contexts separately and uses completed target stories for the overview
+- **Grounded prose** - forbids invented APIs, relationships, examples, and broad marketing claims unless the generated context supports them
+- **Publication stays explicit** - leaves staged files in `{output-root}/{repo-id}/result` unless the user asks to sync them into a consuming site
 ### Why markdown-illustrator?
 
 Markdown-heavy documents often need one image that sells the whole idea fast: a conference opener, article cover, pitch-slide hero, or visual hook that makes the audience want to keep reading. The problem with many prompt workflows is that they branch immediately into model menus, theme toggles, and style comparisons before the document has even been understood.