personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(projman): add token usage estimation reporting

Browse Source 
- 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 <noreply@anthropic.com>
This commit is contained in:
Leo Miranda
2026-02-04 10:20:56 -05:00
parent 044c49ba95
commit d90a8d05af
5 changed files with 155 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
plugins/projman/commands/sprint-close.md
View File

@@ -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

10
plugins/projman/commands/sprint-plan.md
View File

@@ -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

115
plugins/projman/skills/token-budget-report.md Normal file
View File

@@ -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.

19
plugins/projman/skills/visual-output.md
View File

@@ -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.