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/CHANGELOG.md b/CHANGELOG.md index c676855..9cf1d50 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/docs/DEBUGGING-CHECKLIST.md b/docs/DEBUGGING-CHECKLIST.md index d95d98a..b74bdc0 100644 --- a/docs/DEBUGGING-CHECKLIST.md +++ b/docs/DEBUGGING-CHECKLIST.md @@ -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 --- diff --git a/plugins/data-platform/skills/visual-header.md b/plugins/data-platform/skills/visual-header.md index 98df1ac..72b1ce2 100644 --- a/plugins/data-platform/skills/visual-header.md +++ b/plugins/data-platform/skills/visual-header.md @@ -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 diff --git a/plugins/git-flow/commands/git-status.md b/plugins/git-flow/commands/git-status.md index 4741b64..b2b1d6f 100644 --- a/plugins/git-flow/commands/git-status.md +++ b/plugins/git-flow/commands/git-status.md @@ -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 ``` diff --git a/plugins/git-flow/skills/visual-header.md b/plugins/git-flow/skills/visual-header.md index c84108d..70ece8b 100644 --- a/plugins/git-flow/skills/visual-header.md +++ b/plugins/git-flow/skills/visual-header.md @@ -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 | diff --git a/plugins/projman/CONFIGURATION.md b/plugins/projman/CONFIGURATION.md index 476cd04..f66d636 100644 --- a/plugins/projman/CONFIGURATION.md +++ b/plugins/projman/CONFIGURATION.md @@ -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) ``` 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. diff --git a/plugins/viz-platform/claude-md-integration.md b/plugins/viz-platform/claude-md-integration.md index c8ead54..c09f03c 100644 --- a/plugins/viz-platform/claude-md-integration.md +++ b/plugins/viz-platform/claude-md-integration.md @@ -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