diff --git a/.gitignore b/.gitignore index 0cdccc4..ca25cf1 100644 --- a/.gitignore +++ b/.gitignore @@ -84,6 +84,13 @@ Thumbs.db # Claude Code .claude/settings.local.json .claude/history/ +.claude/backups/ + +# Doc Guardian transient files +.doc-guardian-queue + +# Development convenience links +.marketplaces-link # Logs logs/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 1665c3f..5681286 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,55 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). --- +## [6.0.0] - YYYY-MM-DD + +### Added + +#### Plan-Then-Batch Skill Optimization (projman) + +New execution pattern that separates cognitive work from mechanical API operations, reducing skill-related token consumption by ~76-83% during sprint workflows. + +- **`skills/batch-execution.md`** — New skill defining the plan-then-batch protocol: + - Phase 1: Cognitive work with all skills loaded + - Phase 2: Execution manifest (structured plan of all API operations) + - Phase 3: Batch execute API calls using only frontmatter skills + - Phase 4: Batch report with success/failure summary + - Error handling: continue on individual failures, report at end + +- **Frontmatter skill promotion:** + - Planner agent: `mcp-tools-reference` and `batch-execution` promoted to frontmatter (auto-injected, zero re-read cost) + - Orchestrator agent: same promotion + - Eliminates per-operation skill file re-reads during API execution loops + +- **Phase-based skill loading:** + - Planner: 3 phases (validation → analysis → approval) with explicit "read once" instructions + - Orchestrator: 2 phases (startup → dispatch) with same pattern + - New `## Skill Loading Protocol` section replaces flat `## Skills to Load` in agent files + +### Changed + +- **`planning-workflow.md`** — Steps 8-10 restructured: + - Step 8: "Draft Issue Specifications" (no API calls — resolve all parameters first) + - Step 8a: "Batch Execute Issue Creation" (tight API loop, frontmatter skills only) + - Step 9: Merged into Step 8a (dependencies created in batch) + - Step 10: Milestone creation moved before batch (must exist for assignment) + +- **Agent matrix updated:** + - Planner: `body text (14)` → `frontmatter (2) + body text (12)` + - Orchestrator: `body text (12)` → `frontmatter (2) + body text (10)` + +- **`docs/CONFIGURATION.md`** — New "Phase-Based Skill Loading" subsection documenting the pattern + +### Token Impact + +| Scenario | Before | After | Savings | +|----------|--------|-------|---------| +| 6-issue sprint (planning) | ~23,800 lines | ~5,600 lines | ~76% | +| 10-issue sprint (planning) | ~35,000 lines | ~7,000 lines | ~80% | +| 8-issue status updates (orchestrator) | ~9,600 lines | ~1,600 lines | ~83% | + +--- + ## [5.10.0] - 2026-02-03 ### Added diff --git a/CLAUDE.md b/CLAUDE.md index 687ef6b..9c5d590 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -291,8 +291,8 @@ Agents specify their configuration in frontmatter using Claude Code's supported | Plugin | Agent | `model` | `permissionMode` | `disallowedTools` | `skills` | |--------|-------|---------|-------------------|--------------------|----------| -| projman | planner | opus | default | — | body text (14) | -| projman | orchestrator | sonnet | acceptEdits | — | body text (12) | +| projman | planner | opus | default | — | frontmatter (2) + body text (12) | +| projman | orchestrator | sonnet | acceptEdits | — | frontmatter (2) + body text (10) | | projman | executor | sonnet | bypassPermissions | — | frontmatter (7) | | projman | code-reviewer | opus | default | Write, Edit, MultiEdit | frontmatter (4) | | pr-review | coordinator | sonnet | plan | Write, Edit, MultiEdit | — | diff --git a/README.md b/README.md index cca5acd..cb75402 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@ A collection of Claude Code plugins for project management, infrastructure autom AI-guided sprint planning with full Gitea integration. Transforms a proven 15-sprint workflow into a distributable plugin. - Four-agent model: Planner, Orchestrator, Executor, Code Reviewer +- Plan-then-batch execution: skills loaded once per phase, API calls batched for ~80% token savings - Intelligent label suggestions from 43-label taxonomy - Lessons learned capture via Gitea Wiki - Native issue dependencies with parallel execution diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 4664342..398a825 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -516,8 +516,8 @@ Agents specify their configuration in frontmatter using Claude Code's supported | Plugin | Agent | `model` | `permissionMode` | `disallowedTools` | `skills` | |--------|-------|---------|-------------------|--------------------|----------| -| projman | planner | opus | default | — | body text (14) | -| projman | orchestrator | sonnet | acceptEdits | — | body text (12) | +| projman | planner | opus | default | — | frontmatter (2) + body text (12) | +| projman | orchestrator | sonnet | acceptEdits | — | frontmatter (2) + body text (10) | | projman | executor | sonnet | bypassPermissions | — | frontmatter (7) | | projman | code-reviewer | opus | default | Write, Edit, MultiEdit | frontmatter (4) | | pr-review | coordinator | sonnet | plan | Write, Edit, MultiEdit | — | @@ -591,6 +591,40 @@ The `skills` field auto-injects skill file contents into the agent's context win Skill names in frontmatter are resolved relative to the plugin's `skills/` directory. Use the filename without the `.md` extension. +### Phase-Based Skill Loading (Body Text) + +For agents with 8+ skills, use **phase-based loading** in the agent body text. This structures skill reads into logical phases, with explicit instructions to read each skill exactly once. + +**Pattern:** + +```markdown +## Skill Loading Protocol + +**Frontmatter skills (auto-injected, always available — DO NOT re-read these):** +- `skill-a` — description +- `skill-b` — description + +**Phase 1 skills — read ONCE at session start:** +- skills/validation-skill.md +- skills/safety-skill.md + +**Phase 2 skills — read ONCE when entering main work:** +- skills/workflow-skill.md +- skills/domain-skill.md + +**CRITICAL: Read each skill file exactly ONCE. Do NOT re-read skill files between MCP API calls.** +``` + +**Benefits:** +- Frontmatter skills (always needed) are auto-injected — zero file read cost +- Phase skills are read once at the appropriate time — not re-read per API call +- `batch-execution` skill provides protocol for API-heavy phases +- ~76-83% reduction in skill-related token consumption for typical sprints + +**Currently applied to:** +- Planner agent: 2 frontmatter + 12 body text (3 phases) +- Orchestrator agent: 2 frontmatter + 10 body text (2 phases) + --- ## Automatic Validation Features diff --git a/plugins/projman/agents/orchestrator.md b/plugins/projman/agents/orchestrator.md index 3f77d89..4d9f997 100644 --- a/plugins/projman/agents/orchestrator.md +++ b/plugins/projman/agents/orchestrator.md @@ -3,26 +3,35 @@ name: orchestrator description: Sprint orchestration agent - coordinates execution and tracks progress model: sonnet permissionMode: acceptEdits +skills: mcp-tools-reference, batch-execution --- # Sprint Orchestration Agent You are the **Orchestrator Agent** - a concise, action-oriented coordinator who keeps sprints on track. -## Skills to Load +## Skill Loading Protocol -- skills/mcp-tools-reference.md +**Frontmatter skills (auto-injected, always available — DO NOT re-read these):** +- `mcp-tools-reference` — MCP tool signatures for all Gitea operations +- `batch-execution` — Plan-then-batch protocol for API execution + +**Phase 1 skills — read ONCE at session start, before any work begins:** - skills/branch-security.md - skills/sprint-approval.md +- skills/sprint-lifecycle.md +- skills/visual-output.md +- skills/runaway-detection.md + +**Phase 2 skills — read ONCE when sequencing and dispatching work:** - skills/dependency-management.md - skills/lessons-learned.md - skills/git-workflow.md - skills/progress-tracking.md -- skills/runaway-detection.md - skills/wiki-conventions.md - skills/domain-consultation.md -- skills/sprint-lifecycle.md -- skills/visual-output.md + +**CRITICAL: Read each skill file exactly ONCE. Do NOT re-read skill files between MCP API calls. When posting status updates, label changes, or comments across multiple issues, use the batch-execution protocol — queue all operations, execute in a loop using only frontmatter skills.** ## Your Personality diff --git a/plugins/projman/agents/planner.md b/plugins/projman/agents/planner.md index 202e7d4..5c82ca2 100644 --- a/plugins/projman/agents/planner.md +++ b/plugins/projman/agents/planner.md @@ -3,28 +3,39 @@ name: planner description: Sprint planning agent - thoughtful architecture analysis and issue creation model: opus permissionMode: default +skills: mcp-tools-reference, batch-execution --- # Sprint Planning Agent You are the **Planner Agent** - a methodical architect who thoroughly analyzes requirements before creating well-structured plans. -## Skills to Load +## Skill Loading Protocol -- skills/mcp-tools-reference.md +**Frontmatter skills (auto-injected, always available — DO NOT re-read these):** +- `mcp-tools-reference` — MCP tool signatures for all Gitea operations +- `batch-execution` — Plan-then-batch protocol for API execution + +**Phase 1 skills — read ONCE at session start, before any work begins:** - skills/branch-security.md - skills/repo-validation.md +- skills/sprint-lifecycle.md +- skills/visual-output.md + +**Phase 2 skills — read ONCE when entering analysis/planning work:** - skills/input-detection.md - skills/lessons-learned.md - skills/wiki-conventions.md - skills/task-sizing.md - skills/issue-conventions.md -- skills/sprint-approval.md - skills/planning-workflow.md - skills/label-taxonomy/labels-reference.md - skills/domain-consultation.md -- skills/sprint-lifecycle.md -- skills/visual-output.md + +**Phase 3 skills — read ONCE before requesting approval:** +- skills/sprint-approval.md + +**CRITICAL: Read each skill file exactly ONCE. Do NOT re-read skill files between MCP API calls. During batch execution (Step 8a of planning-workflow.md), use ONLY the frontmatter skills — no file reads.** ## Your Personality diff --git a/plugins/projman/commands/sprint-plan.md b/plugins/projman/commands/sprint-plan.md index 31e1ffd..9b86cc8 100644 --- a/plugins/projman/commands/sprint-plan.md +++ b/plugins/projman/commands/sprint-plan.md @@ -7,7 +7,8 @@ agent: planner ## Skills Required -- skills/mcp-tools-reference.md +- skills/mcp-tools-reference.md (frontmatter — auto-injected) +- skills/batch-execution.md (frontmatter — auto-injected) - skills/branch-security.md - skills/repo-validation.md - skills/input-detection.md diff --git a/plugins/projman/commands/sprint-start.md b/plugins/projman/commands/sprint-start.md index 6af22ac..a8fa63d 100644 --- a/plugins/projman/commands/sprint-start.md +++ b/plugins/projman/commands/sprint-start.md @@ -7,7 +7,8 @@ agent: orchestrator ## Skills Required -- skills/mcp-tools-reference.md +- skills/mcp-tools-reference.md (frontmatter — auto-injected) +- skills/batch-execution.md (frontmatter — auto-injected) - skills/branch-security.md - skills/sprint-approval.md - skills/dependency-management.md diff --git a/plugins/projman/skills/batch-execution.md b/plugins/projman/skills/batch-execution.md new file mode 100644 index 0000000..b1ea641 --- /dev/null +++ b/plugins/projman/skills/batch-execution.md @@ -0,0 +1,116 @@ +--- +name: batch-execution +description: Batch MCP API execution to eliminate redundant skill reloading between repetitive operations +--- + +# Batch Execution Pattern + +## Purpose + +Separate cognitive work (analysis, planning, decision-making) from mechanical API execution (issue creation, dependency setup, status updates). Think once with all skills loaded, then execute repetitive API calls in a tight loop with only `mcp-tools-reference.md` needed. + +## When to Use + +- **Planner agent**: After drafting all issues, before calling `create_issue` +- **Orchestrator agent**: When posting status updates, label changes, or comments across multiple issues +- **Any agent**: When making 3+ similar MCP API calls in sequence + +## Protocol + +### Phase 1: Cognitive Work (all skills loaded) + +During analysis, architecture, and planning — use every skill you need. Read files, think deeply, ask questions, resolve ambiguity. This is where the full skill set pays for itself. + +**Output of this phase:** A complete, structured execution plan listing every API operation with all parameters fully resolved. No ambiguity, no placeholders that require re-analysis. + +### Phase 2: Execution Manifest + +Before entering batch mode, produce a structured manifest. This serves as both the execution plan AND a checkpoint for user visibility. Format: + +``` +## Execution Manifest + +### Issue Creation (N items) +1. `create_issue` — title: "[Sprint XX] feat: ..." | labels: [...] | milestone: N +2. `create_issue` — title: "[Sprint XX] fix: ..." | labels: [...] | milestone: N +... + +### Dependency Setup (N items) +1. `create_issue_dependency` — issue: $1 depends_on: $2 +... + +### Milestone Assignment (N items) +1. `update_issue` — issue: $1 milestone: N +... + +### Status/Label Updates (N items) +1. `update_issue` — issue: #N labels: [add "Status/In-Progress"] +... +``` + +Variable references (`$1`, `$2`) resolve to outputs from prior batch operations (e.g., `$1` = issue number returned by first `create_issue`). + +### Phase 3: Batch Execute + +Execute the manifest items in order, grouped by operation type: + +1. **All `create_issue` calls** — collect returned issue numbers +2. **Resolve variable references** — map `$1` → actual issue #45, `$2` → #46, etc. +3. **All `create_issue_dependency` calls** — using resolved numbers +4. **All milestone assignments** — if not done during creation +5. **All status/label updates** — using resolved numbers + +**Rules during batch execution:** +- Do NOT re-read any skill files between calls +- Do NOT re-analyze or second-guess the plan — it was finalized in Phase 1 +- Do NOT add commentary between individual API calls — batch them silently +- DO track success/failure per operation +- DO continue on individual failures (log and report at end) +- DO post a progress summary after each batch group completes + +### Phase 4: Batch Report + +After all operations complete, report results: + +``` +## Batch Execution Complete + +### Issue Creation: 6/6 ✓ +- #45: [Sprint 19] feat: JWT generation +- #46: [Sprint 19] feat: Login endpoint +- #47: [Sprint 19] feat: Token refresh +- #48: [Sprint 19] test: Auth unit tests +- #49: [Sprint 19] docs: API documentation +- #50: [Sprint 19] chore: CI pipeline + +### Dependencies: 4/4 ✓ +- #46 depends on #45 +- #47 depends on #45 +- #48 depends on #46, #47 +- #49 depends on #46 + +### Milestone Assignment: 6/6 ✓ +- All issues assigned to Sprint 19 + +### Failures: 0 +``` + +## Error Handling + +| Error | Action | +|-------|--------| +| Single API call fails | Log error, continue with next item | +| Dependency target missing (prior create failed) | Skip dependency, log as blocked | +| All creates fail | STOP batch, report connection/auth issue | +| Partial milestone assignment | Report which issues weren't assigned | + +After batch completes, if any failures: present failure summary and ask user whether to retry failed operations or continue. + +## Anti-Patterns + +| Wrong | Why | Right | +|-------|-----|-------| +| Re-reading `mcp-tools-reference.md` before each API call | Wastes tokens; you already know the tool signatures | Read once, execute many | +| Interleaving analysis with API calls | Forces full context per call | Finish ALL analysis first, THEN batch execute | +| Calling create_issue one at a time with commentary between | Token overhead per turn | Queue all creates, execute in tight loop | +| Stopping the batch to ask user about individual items | Defeats batching purpose | Complete batch, report results, ask about failures | diff --git a/plugins/projman/skills/planning-workflow.md b/plugins/projman/skills/planning-workflow.md index be808d4..1955481 100644 --- a/plugins/projman/skills/planning-workflow.md +++ b/plugins/projman/skills/planning-workflow.md @@ -84,21 +84,38 @@ Think through: - What dependencies exist? - What are potential risks? -### 8. Create Gitea Issues +### 8. Draft Issue Specifications (DO NOT create yet) -Follow `skills/issue-conventions.md` and `skills/task-sizing.md`: -- Use proper title format: `[Sprint XX] : ` -- Include wiki implementation reference -- Apply appropriate labels using `suggest_labels` -- **Refuse to create L/XL tasks without breakdown** +Follow `skills/issue-conventions.md` and `skills/task-sizing.md` to prepare the complete specification for ALL issues. **Do NOT call `create_issue` yet.** -### 9. Set Up Dependencies +For each issue, resolve completely: +- Title: `[Sprint XX] : ` +- Body: Full description with wiki reference, acceptance criteria, technical notes +- Labels: Use `suggest_labels` to determine, then finalize the list +- Milestone: The sprint milestone (create first if needed) +- Dependencies: Which issues depend on which (by draft order index) -```python -create_issue_dependency(repo="org/repo", issue_number=46, depends_on=45) -``` +**Refuse to create L/XL tasks without breakdown.** -### 10. Create or Select Milestone +Output: A complete execution manifest per `skills/batch-execution.md` Phase 2 format. + +### 8a. Batch Execute Issue Creation + +Follow `skills/batch-execution.md` Phase 3: +1. Execute all `create_issue` calls — collect returned issue numbers +2. Execute all `create_issue_dependency` calls — using collected numbers +3. Assign all issues to milestone +4. Report batch results per Phase 4 format + +**Only `skills/mcp-tools-reference.md` is needed for this step.** Do NOT re-read other skill files. + +### 9. (Merged into Step 8a) + +Dependencies are now created as part of the batch execution in Step 8a. No separate step needed. + +### 10. Create or Select Milestone (before batch) + +**This step runs BEFORE Step 8a** — the milestone must exist before batch issue creation can assign to it. ```python create_milestone( @@ -109,7 +126,7 @@ create_milestone( ) ``` -Assign issues to the milestone. +If milestone already exists, select it. Record the milestone ID for use in the batch manifest. ### 11. Request Sprint Approval