update-agent-context.sh bloats CLAUDE.md with per-feature tech-stack entries that duplicate project docs

[arun-gupta]

Summary

.specify/scripts/bash/update-agent-context.sh (invoked from the /speckit.plan workflow) appends two sections to CLAUDE.md on every feature plan:

• Active Technologies — one bullet per feature, repeating the Technical Context language/framework line
• Recent Changes — a bullet summarising the latest feature's tech addition

Over a project's lifetime this grows unbounded. For a project with 50+ features and a stable tech stack, CLAUDE.md ends up with 100+ lines of near-identical bullets ("TypeScript 5.x (Next.js 16+) + …") — all of them duplicating what's already in the project's own DEVELOPMENT / README / architecture docs, and all of them paid for as input tokens on every Claude Code session.

Why it hurts

1. Duplication with project docs: most SpecKit projects already have a canonical source for tech stack (README.md, docs/DEVELOPMENT.md, or similar) that CLAUDE.md can link to. The per-feature bullets restate that canonical info without adding signal Claude can act on.
2. Merge-conflict surface: because every feature plan writes to the same section, parallel feature branches conflict on CLAUDE.md. This is a frequent papercut for projects running multiple worktrees or long-lived branches.
3. Context-window cost: CLAUDE.md is loaded on every Claude Code session. Every unnecessary line is paid for repeatedly.
4. Low signal-to-noise: when the stack is stable (e.g. a TypeScript monorepo), bullet N looks essentially identical to bullet 1. Claude gains nothing from reading both.

Repro

1. Init SpecKit in a repo: specify init.
2. Run /speckit.specify + /speckit.plan for feature 1. CLAUDE.md gains an "Active Technologies" entry.
3. Do the same for feature 2 with the same tech stack. CLAUDE.md now has two near-identical bullets. Repeat.
4. After N features, CLAUDE.md has N repeated bullets plus an N-long Recent Changes section.

Suggested directions

Not prescribing a single fix — curious to hear maintainer thoughts. Some possibilities:

• Make population opt-in via an init-options.json flag (e.g. "populate_claude_md": false). Default could stay as-is to avoid breaking existing projects.
• Deduplicate: if the same language/framework line already exists in the Active Technologies section, skip the append.
• Cap length: trim to the last N bullets, or snapshot into a separate file after a threshold.
• Section-pointer instead of mirror: by default have update-agent-context.sh emit a single line like "See docs/DEVELOPMENT.md for tech stack" rather than per-feature bullets. If the user explicitly wants per-feature tracking, opt into the verbose mode.

Happy to send a PR for whichever direction aligns with your design intent.

Environment

• SpecKit version: 0.4.4.dev0
• Claude Code project using bash scripts (.specify/scripts/bash/)
• Observed while working on [#249] Align SpecKit branch/spec numbering with GitHub issue number arun-gupta/repo-pulse#282

[mnriem]

Will be closed by the larger scoped #2259 Note please update your CLI as a lot of things have been updated since 0.4.4

[arun-gupta]

@mnriem turns out my release was pinned, now on the latest release.