feat(spec): opt-in AI usage tracking for spec new#20
Merged
Conversation
skapoor8
commented
Jul 9, 2026
Gate AI usage tracking behind a new --usage flag on /spec new. When set, a background subagent monitors the executing agent's session files and writes token/tool telemetry to ai-usage.md inside the plan directory. Behaviour is byte-for-byte unchanged when the flag is absent. **Wiring** - Add USAGE_MODE parsing plus monitor and finalize steps to the new workflow. - Add ai-usage-template.md and usage-monitor.md references. - Document --usage in SKILL.md. **Session detection and aggregation** - Select the cwd-matching session file (skip the subagent's own transcript) so a background monitor measures the parent planning session, not itself. - Bound token and tool aggregation to USAGE_START_EPOCH via each line's timestamp, matching the advertised planning window. - Guard the best-effort other-agent probe with nullglob/globstar so placeholder globs expand instead of staying literal. - Support Claude Code as a first-class source and other agents on a best-effort basis with graceful degradation. **Reporting** - Relabel the usage Total row "Total (all classes)" and clarify it is a tokens-processed record, not a cost figure.
skapoor8
force-pushed
the
spec-new-usage-tracking
branch
from
0b6d6bb to
1cd972e
Compare
github-actions Bot
pushed a commit
that referenced
this pull request
Jul 9, 2026
## [1.57.0](v1.56.0...v1.57.0) (2026-07-09) ### Features * **spec:** add opt-in AI usage tracking to spec new ([#20](#20)) Gate AI usage tracking behind a new --usage flag on /spec new. When set, a background subagent monitors the executing agent's session files and writes token/tool telemetry to ai-usage.md inside the plan directory. Behaviour is byte-for-byte unchanged when the flag is absent. **Wiring** - Add USAGE_MODE parsing plus monitor and finalize steps to the new workflow. - Add ai-usage-template.md and usage-monitor.md references. - Document --usage in SKILL.md. **Session detection and aggregation** - Select the cwd-matching session file (skip the subagent's own transcript) so a background monitor measures the parent planning session, not itself. - Bound token and tool aggregation to USAGE_START_EPOCH via each line's timestamp, matching the advertised planning window. - Guard the best-effort other-agent probe with nullglob/globstar so placeholder globs expand instead of staying literal. - Support Claude Code as a first-class source and other agents on a best-effort basis with graceful degradation. **Reporting** - Relabel the usage Total row "Total (all classes)" and clarify it is a tokens-processed record, not a cost figure.
|
🎉 This PR is included in version 1.57.0 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
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
1 participant
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.
Changes
--usageflag to/spec new. AI usage tracking runs if and only if the flag is passed; without it, nothing is tracked and no usage file is written.ai-usage.mdin the plan dir. It never mixes intoplan.md,user-guide.md, or implementation files.New references:
skills/spec/references/usage-monitor.md(Steps A-C: locate, aggregate, write) andskills/spec/references/ai-usage-template.md(theai-usage.mdlayout, measured and unavailable variants).new.mdwires the monitor at Step 5.2u (launch) and Step 6 (finalize/block).Validation
/spec new <objective>without--usageproduces noai-usage.md/spec new --usage <objective>writes{PLAN_DIR}/ai-usage.mdwith token and tool tablesFuture Work