Merge pull request 'feat(projman): add plan-then-batch skill optimization' (#421) from feat/plan-then-batch-optimization into development

Reviewed-on: #421

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

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

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

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

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

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
 

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
 

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

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

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 |

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] <type>: <description>`
-- 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] <type>: <description>`
+- 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