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

Merge pull request 'fix: v7.0.1 stale reference cleanup + token usage reporting' (#425) from fix/v7-stale-refs-and-token-reporting into development

Browse Source 
Reviewed-on: #425
This commit was merged in pull request #425.
This commit is contained in:
Leo Miranda
2026-02-04 15:25:37 +00:00
parent 76105e98e0 871d1bff58
commit 9eece4daa3
12 changed files with 191 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@@ -132,4 +132,5 @@ site/
*credentials*
*secret*
*token*
!**/token-budget-report.md
!.gitkeep

14
CHANGELOG.md
View File

@@ -6,6 +6,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
## [Unreleased]
### Fixed
- **docs:** Stale command references in data-platform visual-header.md and viz-platform claude-md-integration.md updated to v7.0.0 namespaced names
- **docs:** git-flow visual-header.md and git-status.md quick actions updated to namespaced commands
- **docs:** projman/CONFIGURATION.md and docs/DEBUGGING-CHECKLIST.md updated with correct command names
### Added
- **projman:** Token usage estimation reporting at sprint workflow boundaries
- New skill: `token-budget-report.md` with MCP overhead and skill loading estimation model
- Token report displayed at end of `/sprint-plan` and `/sprint-close`
- On-demand via `/sprint-status --tokens`
- Helps identify which phases and components consume the most context budget
---
## [7.0.0] - 2026-02-03

4
docs/DEBUGGING-CHECKLIST.md
View File

@@ -279,8 +279,8 @@ Error: Could not find a suitable TLS CA certificate bundle, invalid path:
Use these commands for automated checking:
- `/debug report` - Run full diagnostics, create issue if problems found
- `/debug review` - Investigate existing diagnostic issues and propose fixes
- `/pm-debug report` - Run full diagnostics, create issue if problems found
- `/pm-debug review` - Investigate existing diagnostic issues and propose fixes
---

16
plugins/data-platform/skills/visual-header.md
View File

@@ -14,16 +14,18 @@ Display at the start of every command execution:
| Command | Header Text |
|---------|-------------|
| initial-setup | Setup Wizard |
| ingest | Ingest |
| profile | Data Profile |
| schema | Schema Explorer |
| data-setup | Setup Wizard |
| data-ingest | Ingest |
| data-profile | Data Profile |
| data-schema | Schema Explorer |
| data-quality | Data Quality |
| run | dbt Run |
| data-run | dbt Run |
| dbt-test | dbt Tests |
| lineage | Lineage |
| data-lineage | Lineage |
| lineage-viz | Lineage Visualization |
| explain | Model Explanation |
| data-explain | Model Explanation |
| data-review | Data Review |
| data-gate | Data Gate |
## Summary Box Format

4
plugins/git-flow/commands/git-status.md
View File

@@ -51,6 +51,6 @@ Unstaged:
2. Ready to commit with 1 staged file
--- Quick Actions ---
/commit - Commit staged changes
/commit-push - Commit and push
/git-commit - Commit staged changes
/git-commit-push - Commit and push
```

8
plugins/git-flow/skills/visual-header.md
View File

@@ -19,28 +19,28 @@ Standard header format for consistent visual output across all git-flow commands
## Command Headers
### /commit
### /git-commit
```
+----------------------------------------------------------------------+
| GIT-FLOW Smart Commit |
+----------------------------------------------------------------------+
```
### /commit-push
### /git-commit-push
```
+----------------------------------------------------------------------+
| GIT-FLOW Commit & Push |
+----------------------------------------------------------------------+
```
### /commit-sync
### /git-commit-sync
```
+----------------------------------------------------------------------+
| GIT-FLOW Commit Sync |
+----------------------------------------------------------------------+
```
### /commit-merge
### /git-commit-merge
```
+----------------------------------------------------------------------+
| GIT-FLOW Commit & Merge |

4
plugins/projman/CONFIGURATION.md
View File

@@ -5,6 +5,6 @@ See **[docs/CONFIGURATION.md](../../docs/CONFIGURATION.md)** for complete setup
## Quick Commands
```
/initial-setup # First time on this machine
/project-init # New project (system already configured)
/pm-setup --full # First time on this machine
/pm-setup --quick # New project (system already configured)
```

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.

6
plugins/viz-platform/claude-md-integration.md
View File

@@ -44,9 +44,9 @@ If using with data-platform, add this section:
## Data + Visualization Workflow
### Data Loading (data-platform)
- `/ingest {file}` - Load CSV, Parquet, or JSON
- `/schema {table}` - View database schema
- `/profile {data_ref}` - Statistical summary
- `/data-ingest {file}` - Load CSV, Parquet, or JSON
- `/data-schema {table}` - View database schema
- `/data-profile {data_ref}` - Statistical summary
### Visualization (viz-platform)
- `/viz-chart {type}` - Create charts from loaded data