From d90a8d05af4856a078fe9a6b3a6f4acfe5c00b40 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Wed, 4 Feb 2026 10:20:56 -0500 Subject: [PATCH] feat(projman): add token usage estimation reporting - New skill: token-budget-report.md with MCP overhead and skill loading estimation model based on known file sizes and static overhead tables - Sprint-plan displays token report after planning complete - Sprint-close displays token report after lessons captured - Visual-output.md updated with token report format - .gitignore exception for token-budget-report.md (not API tokens) Helps identify which phases and components consume the most context budget. Co-Authored-By: Claude Opus 4.5 --- .gitignore | 1 + plugins/projman/commands/sprint-close.md | 10 ++ plugins/projman/commands/sprint-plan.md | 10 ++ plugins/projman/skills/token-budget-report.md | 115 ++++++++++++++++++ plugins/projman/skills/visual-output.md | 19 +++ 5 files changed, 155 insertions(+) create mode 100644 plugins/projman/skills/token-budget-report.md diff --git a/.gitignore b/.gitignore index ca25cf1..b6ea4d4 100644 --- a/.gitignore +++ b/.gitignore @@ -132,4 +132,5 @@ site/ *credentials* *secret* *token* +!**/token-budget-report.md !.gitkeep diff --git a/plugins/projman/commands/sprint-close.md b/plugins/projman/commands/sprint-close.md index b8d4f30..a474d84 100644 --- a/plugins/projman/commands/sprint-close.md +++ b/plugins/projman/commands/sprint-close.md @@ -14,6 +14,7 @@ agent: orchestrator - skills/progress-tracking.md - skills/git-workflow.md - skills/sprint-lifecycle.md +- skills/token-budget-report.md ## Purpose @@ -82,3 +83,12 @@ If the sprint was linked to an RFC: ║ [Sprint Name] ║ ╚══════════════════════════════════════════════════════════════════╝ ``` + +## Final Step: Token Budget Report + +After displaying the closing summary and completing all workflow steps, generate a Token Budget Report per `skills/token-budget-report.md`. + +- Phase: CLOSING +- List all skills that were loaded during this closing session +- Use the orchestrator agent's model (sonnet) for agent overhead +- Display the formatted report diff --git a/plugins/projman/commands/sprint-plan.md b/plugins/projman/commands/sprint-plan.md index 9b86cc8..27b4318 100644 --- a/plugins/projman/commands/sprint-plan.md +++ b/plugins/projman/commands/sprint-plan.md @@ -20,6 +20,7 @@ agent: planner - skills/planning-workflow.md - skills/label-taxonomy/labels-reference.md - skills/sprint-lifecycle.md +- skills/token-budget-report.md ## Purpose @@ -57,3 +58,12 @@ Execute the planning workflow as defined in `skills/planning-workflow.md`. ║ [Sprint Name] ║ ╚══════════════════════════════════════════════════════════════════╝ ``` + +## Final Step: Token Budget Report + +After displaying the planning summary and gaining sprint approval, generate a Token Budget Report per `skills/token-budget-report.md`. + +- Phase: PLANNING +- List all skills that were loaded during this planning session +- Use the planner agent's model (sonnet) for agent overhead +- Display the formatted report diff --git a/plugins/projman/skills/token-budget-report.md b/plugins/projman/skills/token-budget-report.md new file mode 100644 index 0000000..2c9fbba --- /dev/null +++ b/plugins/projman/skills/token-budget-report.md @@ -0,0 +1,115 @@ +--- +description: Token consumption estimation model and display format for sprint workflows +--- + +# Token Budget Report + +## Purpose + +Provides directional token consumption estimates at sprint workflow boundaries. Not exact — Claude Code doesn't expose token metrics — but accurate enough to identify which phases and components consume the most context budget. + +## When to Display + +- End of `/sprint-plan` (after all issues created) +- End of `/sprint-close` (after lessons captured) +- On explicit request: `/sprint-status --tokens` + +--- + +## Estimation Model + +### MCP Tool Definitions (Static Overhead) + +These are loaded once at session start. Update this table if MCP servers change. + +| MCP Server | Default Tools | Est. Tokens | With Module Filter | +|------------|--------------|-------------|-------------------| +| netbox | 182 | ~19,810 | ~4,500 (dcim,ipam,virt,extras) | +| gitea | 36 | ~4,785 | — | +| data-platform | 32 | ~3,458 | — | +| viz-platform | 20 | ~3,055 | — | +| contract-validator | 8 | ~1,048 | — | +| **Total (default)** | **278** | **~32,156** | — | +| **Total (filtered)** | **~139** | **~16,846** | — | + +### Skill Loading (Per Phase) + +| Phase | Typical Skills Loaded | Est. Tokens | +|-------|----------------------|-------------| +| Planning (`/sprint-plan`) | mcp-tools-reference, label-taxonomy, sprint-planning, architecture-analysis, rfc-workflow | ~3,000–5,000 | +| Execution (`/sprint-start`) | mcp-tools-reference, branch-security, plan-then-batch | ~2,000–3,000 | +| Review (`/pm-review`) | mcp-tools-reference, review-checklist | ~1,500–2,500 | +| Close (`/sprint-close`) | mcp-tools-reference, sprint-lifecycle, lessons-learned | ~2,000–3,000 | + +To get actual numbers: count characters in each skill file loaded during the phase, divide by 4. + +### Agent Overhead + +| Agent | Model | Est. Overhead per Invocation | +|-------|-------|------------------------------| +| Planner | sonnet | ~500 tokens (frontmatter + system context) | +| Orchestrator | sonnet | ~500 tokens | +| Executor | sonnet | ~400 tokens | +| Code Reviewer | sonnet | ~400 tokens | + +--- + +## Display Format + +``` ++-- Token Budget Report -----------------------------------------------+ +| Phase: [PLANNING / CLOSING] | +| Sprint: [Sprint Name] | ++----------------------------------------------------------------------+ +| | +| MCP Overhead (session-wide): | +| netbox ........... ~4,500 tk (filtered: dcim,ipam,virt,extras) | +| gitea ............ ~4,785 tk | +| data-platform .... ~3,458 tk | +| viz-platform ..... ~3,055 tk | +| contract-valid ... ~1,048 tk | +| Subtotal ......... ~16,846 tk | +| | +| This Phase: | +| Skills loaded .... ~X,XXX tk (N files) | +| Agent overhead ... ~X,XXX tk (model: sonnet) | +| Command file ..... ~XXX tk | +| Subtotal ......... ~X,XXX tk | +| | +| Estimated Session Total: ~XX,XXX tk | +| Typical Claude Code Budget: ~200,000 tk | +| Estimated Usage: ~XX% | +| | +| Tip: Run `/doctor` for exact MCP overhead numbers. | ++----------------------------------------------------------------------+ +``` + +--- + +## Instructions for the Agent + +When generating this report: + +1. **MCP Overhead**: List the MCP servers from `.mcp.json` and use the static token estimates from the table above. If `NETBOX_ENABLED_MODULES` is set in the environment, use the filtered estimate for netbox. + +2. **Skills Loaded**: Count the skill files that were loaded (referenced in the command's "Skills Required" section). Estimate tokens by reading each file's character count and dividing by 4. + +3. **Agent Overhead**: Use the table above based on which agent ran during this phase. + +4. **Totals**: Sum the phase subtotal. Add to MCP overhead for session estimate. + +5. **Percentage**: Express as a percentage of ~200,000 tokens (typical Claude Code context window). + +--- + +## Accuracy Disclaimer + +These are estimates based on known file sizes and static overhead tables. Actual consumption varies based on: +- Conversation length +- Tool call results (especially large grep/read outputs) +- File content read during the session +- Number of agent invocations + +For exact MCP overhead, run `/doctor`. + +This report helps identify which *components* consume the most budget — not the precise total. diff --git a/plugins/projman/skills/visual-output.md b/plugins/projman/skills/visual-output.md index a546ca2..727fea1 100644 --- a/plugins/projman/skills/visual-output.md +++ b/plugins/projman/skills/visual-output.md @@ -99,3 +99,22 @@ For domain gate results displayed by orchestrator: | Hourglass | In progress | | Empty box | Pending / Not started | | Warning | Warning | + +--- + +## Token Budget Report + +Displayed at end of planning and closing phases: + +``` ++-- Token Budget Report -----------------------------------------------+ +| Phase: [PHASE NAME] | +| Sprint: [Sprint Name] | ++----------------------------------------------------------------------+ +| MCP Overhead: ~XX,XXX tk | +| Phase Cost: ~X,XXX tk (skills: N, agent: model) | +| Est. Total: ~XX,XXX tk (~XX% of budget) | ++----------------------------------------------------------------------+ +``` + +See `skills/token-budget-report.md` for full format and estimation model.