V0.4.0/git story teller#11
Merged
gimlichael merged 14 commits intomainfrom May 3, 2026
Merged
Conversation
Projects using .bot/ folder for local agentic workspaces and ephemeral state should not leak those artifacts into source control.
Introduce deterministic repository story generation workflow. The skill bundles a .NET file-based context generator (scripts/story.cs) that clones a repository, discovers package targets, extracts deterministic evidence using repomix, and writes manifest, instructions, and context files. The agent then uses that evidence to write target stories before generating the overview, enforcing grounding, context-budget awareness, and no-invention rules.
Add git-story-teller to the installation instructions table and usage guidance sections. Explain the bundled C# runner approach, repository-generic input contract, deterministic output structure, and grounding-first prose model.
Review Summary by QodoAdd git-story-teller skill with deterministic context packing and Karpathy agent guidelines
WalkthroughsDescription• Introduces git-story-teller skill for deterministic repository story generation - Bundles .NET 10 file-based context extractor (scripts/story.cs) with 1100+ lines - Discovers .NET package targets, extracts grounded evidence via Repomix with web API and .NET fallbacks - Generates manifest, instructions, and per-target context files for agent-authored prose • Adds Karpathy rules to AGENTS.md for LLM-driven coding best practices - Think before coding, simplicity first, surgical changes, goal-driven execution • Documents git-story-teller in README with installation, usage, and workflow guidance • Updates .gitignore to recognize .bot/ workspace pattern for local agentic workspaces • Releases v0.4.0 with changelog entries and version links Diagramflowchart LR
RepoURL["Repository URL"]
Runner["scripts/story.cs<br/>Runner"]
Repomix["Repomix Local"]
WebAPI["Repomix Web API"]
DotNetPacker[".NET Fallback<br/>Packer"]
Context["Context Files<br/>manifest.json<br/>instructions.md<br/>*.context.md"]
Agent["Agent Prose<br/>Writer"]
Results["Result Files<br/>result/Index.md<br/>result/{Target}.md"]
RepoURL -->|"--repo-url"| Runner
Runner -->|"tries first"| Repomix
Repomix -->|"unavailable"| WebAPI
WebAPI -->|"unavailable"| DotNetPacker
Repomix -->|"success"| Context
WebAPI -->|"success"| Context
DotNetPacker -->|"success"| Context
Context -->|"reads"| Agent
Agent -->|"writes"| Results
File Changes1. skills/git-story-teller/scripts/story.cs
|
Code Review by Qodo
1. SKILL description lacks triggers
|
Greptile SummaryThis PR introduces the
Confidence Score: 3/5Mergeable but the missing process timeout in RunProcessAsync is a real operational risk worth addressing before wide use. One P1 finding (no timeout on external processes) caps the score below 4. The rest of the changes are clean documentation, eval, and guideline additions. The P1 affects the core runner path but does not cause data corruption or security exposure. skills/git-story-teller/scripts/story.cs — RunProcessAsync and the /**/ glob branch in MatchesIncludePattern. Important Files Changed
Sequence DiagramsequenceDiagram
participant User
participant Agent
participant Runner as story.cs (Runner)
participant Git
participant Repomix as npx repomix
participant RepomixAPI as Repomix Web API
participant DotNetPacker as Built-in .NET Packer
User->>Agent: git-story-teller (repo-url, output-root)
Agent->>Runner: dotnet run --file story.cs -- --repo-url --output-root
Runner->>Git: git clone --depth 1 repo-url
Git-->>Runner: cloned repo
Runner->>Runner: DiscoverTargets (src/*.csproj)
loop Each target
Runner->>Repomix: npx repomix --include ...
alt Repomix available
Repomix-->>Runner: XML context
else npx/npm unavailable (GitHub HTTPS only)
Runner->>RepomixAPI: POST api.repomix.com/api/pack
alt Web API available
RepomixAPI-->>Runner: NDJSON result
else Web API unavailable
Runner->>DotNetPacker: PackWithDotNetPackerAsync
DotNetPacker-->>Runner: XML (lower fidelity)
end
end
Runner->>Runner: Write target.context.md
end
Runner->>Runner: Write overview.context.md, manifest.json, instructions.md
Runner-->>Agent: workspace ready
Agent->>Agent: Read manifest.json + instructions.md
loop Each target (one at a time)
Agent->>Agent: Read target.context.md, write result/target.md
end
Agent->>Agent: Read overview.context.md + target results, write result/Index.md
Agent-->>User: Story workspace complete
Prompt To Fix All With AIFix the following 3 code review issues. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 3
skills/git-story-teller/scripts/story.cs:984-1015
**No timeout on external processes**
`RunProcessAsync` has no timeout or cancellation token. A `git clone` against a large repository, a slow network that stalls without fully disconnecting, or a hung `npx` invocation will block the script indefinitely. `Process.WaitForExitAsync` accepts a `CancellationToken`, so a `CancellationTokenSource` with a configurable (or fixed) deadline would bound the hang window and let the caller surface a clear error.
### Issue 2 of 3
skills/git-story-teller/scripts/story.cs:855-860
**`/**/` glob does not match zero-depth paths**
Standard glob semantics treat `a/**/b` as matching `a/b` (zero intermediate directories) as well as `a/x/b`, `a/x/y/b`, etc. The current implementation's `EndsWith("/" + parts[1])` check requires at least one separator before the trailing segment, so the pattern `.nuget/**/README.md` will not match `.nuget/README.md`. If a package places its README directly under `.nuget/`, that file would be silently omitted when the built-in fallback packer is active.
### Issue 3 of 3
.gitignore:20
**Missing newline at end of file**
The last line `.bot/*` has no trailing newline, which is flagged by many editors and linters and can cause unexpected diffs in future patches.
```suggestion
.bot/*
```
Reviews (1): Last reviewed commit: "📝 update overview story prompt to use p..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
Comment on lines
+2
to
+4
| name: git-story-teller | ||
| description: > | ||
| Generate source-grounded repository story markdown from deterministic ContentSync context bundles. Use when the user asks to create, refresh, or complete repo/package stories, family or project overview pages, .bot/stories output, ContentSync story workflows, or result/Index.md plus result/{TargetName}.md files for any repository URL. The skill runs its bundled .NET file-based context generator, writes target stories first, then writes the overview from completed target stories, and enforces grounding, context-budget, and no-invention rules. |
There was a problem hiding this comment.
1. Skill description lacks triggers 📘 Rule violation ✧ Quality
The new skills/git-story-teller/SKILL.md frontmatter description explains purpose/usage but does not include at least two concrete trigger phrases users might say. This violates the requirement to document trigger phrases for discoverability and consistent invocation.
Agent Prompt
## Issue description
`skills/git-story-teller/SKILL.md` frontmatter `description` is missing the required “Trigger phrases” section with at least 2 concrete example user utterances.
## Issue Context
Compliance requires skill descriptions to include: (1) what it does, (2) when to use it, and (3) trigger phrases users might actually say.
## Fix Focus Areas
- skills/git-story-teller/SKILL.md[1-5]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+154
to
+161
| var sanitized = Regex.Replace(lastSegment, "[^A-Za-z0-9._-]", "-").Trim('-', '.', '_'); | ||
| if (string.IsNullOrWhiteSpace(sanitized)) | ||
| { | ||
| throw new InvalidOperationException("Could not derive a filesystem-safe repo id from --repo-url."); | ||
| } | ||
|
|
||
| return sanitized.ToLowerInvariant(); | ||
| } |
There was a problem hiding this comment.
2. deriverepoid() lowercases repo-id 📘 Rule violation ≡ Correctness
The new runner forces the derived repo-id to lowercase via ToLowerInvariant(), even though repo-id is a generic identifier derived from the repo name and is not documented/typed as requiring lowercase. This violates the restriction against blanket lowercasing of identifiers unless explicitly required.
Agent Prompt
## Issue description
`DeriveRepoId()` returns `sanitized.ToLowerInvariant()`, which lowercases a generic identifier (`repo-id`) without an explicit schema/doc requirement that this field must be lowercase.
## Issue Context
The compliance rule allows lowercasing only when the field is explicitly defined as a lowercase identifier. `repo-id` is derived from the repository URL and used for workspace paths, so either preserve case or explicitly constrain/document the field as lowercase in the skill contract.
## Fix Focus Areas
- skills/git-story-teller/scripts/story.cs[139-161]
- skills/git-story-teller/SKILL.md[50-55]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+745
to
+763
| private static bool CanUseRepomixWebApi(string repoUrl) | ||
| { | ||
| return Uri.TryCreate(repoUrl, UriKind.Absolute, out var uri) | ||
| && uri.Scheme is "http" or "https" | ||
| && string.Equals(uri.Host, "github.com", StringComparison.OrdinalIgnoreCase); | ||
| } | ||
|
|
||
| private static async Task<string> PackWithRepomixWebApiAsync(string repoUrl, string includes) | ||
| { | ||
| using var http = new HttpClient(); | ||
| using var content = new MultipartFormDataContent | ||
| { | ||
| { new StringContent(repoUrl, Encoding.UTF8), "url" }, | ||
| { new StringContent("xml", Encoding.UTF8), "format" }, | ||
| { new StringContent(BuildRepomixWebOptions(includes), Encoding.UTF8), "options" } | ||
| }; | ||
|
|
||
| using var response = await http.PostAsync("https://api.repomix.com/api/pack", content); | ||
| var body = await response.Content.ReadAsStringAsync(); |
There was a problem hiding this comment.
3. Repo url credential exfiltration 🐞 Bug ⛨ Security
When local Repomix fails, the runner posts the provided --repo-url verbatim to the public Repomix API for any https://github.com/... URL. If the URL contains embedded credentials/tokens (userinfo) or other sensitive query data, those secrets are sent to a third-party service.
Agent Prompt
### Issue description
`PackWithRepomixWebApiAsync` sends `repoUrl` to `https://api.repomix.com/api/pack` without checking for embedded credentials (URI userinfo) or other sensitive components.
### Issue Context
The web fallback is triggered for `https://github.com/...` URLs when local Repomix is unavailable, but this can unintentionally transmit secrets if users pass credentialed URLs (common in CI).
### Fix Focus Areas
- skills/git-story-teller/scripts/story.cs[745-789]
- skills/git-story-teller/scripts/story.cs[752-763]
### What to change
- Parse `repoUrl` as a `Uri` and **reject** (preferred) or **strip** `UserInfo` before calling the web API.
- Consider also rejecting URLs with non-empty `Query`/`Fragment` (or stripping them) for the web-API path.
- Print a clear warning before using the web API fallback that the URL is being sent to a third party.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
- Fix glob pattern matching for zero-depth paths (/**/suffix now matches prefix/suffix) - Add configurable timeout and cancellation token to RunProcessAsync (default 5 min)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces the new
git-story-tellerskill for deterministic repository story generation, improves documentation, and adds foundational agent guidelines. The most important changes are grouped below.New Skill: Repository Story Generation
git-story-tellerskill, which generates source-grounded repository stories using a bundled .NET context extractor (scripts/story.cs). It produces a deterministic workspace, supports Repomix and web API fallbacks, and enforces grounding and context-budget rules. [1] [2] [3] [4] [5]Documentation and Guidelines
git-story-tellerinstallation and usage in theREADME.md, including workflow details, expected outputs, and integration notes. [1] [2] [3]AGENTS.md—a set of behavioral guidelines for LLM-driven coding, emphasizing explicit assumptions, simplicity, minimal changes, and goal-driven execution.Release Management
0.4.0release in theCHANGELOG.md, summarizing the addition ofgit-story-teller, the bundled context packer, Karpathy rules, and workspace improvements.0.4.0.Workspace and Tooling
.gitignoreand documentation to recognize the.bot/workspace pattern for local agentic workspaces and ephemeral state.These changes lay the groundwork for robust, reproducible repository story generation and establish clear agent coding practices.