aiskillstore/document-writing-coordination

Document Writing Coordination via VibeKanban

Coordinate multi-section document creation by delegating to doc writer agents through VibeKanban task management. The coordinator (Chief of Staff) plans and monitors but never writes content directly.

Core Principles

Role Separation

| Role | Responsibility | Does NOT | | --------------------- | ---------------------------------- | ------------------ | | Coordinator (You) | Outline, delegate, monitor, review | Write content | | Doc Writers | Write assigned sections | Plan or coordinate | | Reviewer (You) | Approve/reject, ensure consistency | Implement fixes |

Workflow Overview

1. Explore codebase → Understand scope
2. Create outline → Scaffold document structure
3. Create VK tasks → One per section
4. Spawn attempts → Launch doc writer agents
5. Monitor → Poll status periodically
6. Review → Approve or send back
7. Consistency check → After each merge
8. Complete → When no pending tasks remain

Phase 1: Document Outline Creation

Explore First

Before creating the outline, thoroughly explore the codebase:

Use Task tool with subagent_type=Explore to understand:
- Project structure and components
- Key technologies and patterns
- Existing documentation
- Recent changes and evolution

Create Skeleton Document

Write the document outline with:

• Table of contents with all sections
• HTML comments in each section describing scope
• "TODO: Section pending" placeholder for content
• Clear section numbering (1, 2, 3.1, 3.2, etc.)

Example section scaffold:

## 3.1 Component Name

<!--
SCOPE: What this section covers
- Key topics to address
- Source files to reference
- Diagrams to include
-->

TODO: Section pending

Phase 2: Task Creation

Task Description Template

Each VK task MUST include:

## Task

Write Section X "Section Title" of `/path/to/document.md`.

## Required Skill

**MUST use doc writer skill** - Invoke `document-skills:doc-coauthoring` skill before writing.

## Context

[2-3 sentences of essential background for a fresh agent]

## Scope

- [Bullet list of what to cover]
- [Specific topics]
- [Diagrams to create]

## Source Files to Reference

- `path/to/relevant/file.ts`
- `path/to/another/file.md`

## Output

Edit `/path/to/document.md` replacing "TODO: Section pending" under Section X with complete content.

## Delegation Rule

If this section exceeds [N] words, scaffold subsections and create new VK tasks using vibe_kanban MCP tools (project_id: [UUID]):

- X.1 Subsection A
- X.2 Subsection B

## VK Task ID: [task-uuid]

When done, mark task as "inreview" in VK.

Key Task Properties

• Title format: Doc: Section X.Y - Section Name
• Context: Succinct, self-contained for fresh agent
• Skill requirement: Explicit doc-coauthoring skill invocation
• Delegation rule: Word limit triggers for cascading
• VK tracking: Include task ID for status updates

Creating Tasks via MCP

mcp__vibe_kanban__create_task:
  project_id: [project-uuid]
  title: "Doc: Section 1 - Executive Summary"
  description: [full template above]

Phase 3: Spawning Attempts

VK Attempt Requirements

To spawn agents via VK start_workspace_session:

mcp__vibe_kanban__start_workspace_session:
  task_id: [task-uuid]
  executor: CLAUDE_CODE
  repos: [{repo_id: [repo-uuid], base_branch: main}]

Critical: Requires repo_id from VK project configuration. Use list_repos to retrieve, or ask user to configure repository in VK dashboard first.

Fallback: Task Tool

If VK repos not configured, use hybrid approach:

1. Update VK task status to inprogress
2. Spawn agent via Task tool with full context
3. Update VK to inreview when agent completes

mcp__vibe_kanban__update_task:
  task_id: [uuid]
  status: inprogress

Task tool:
  subagent_type: general-purpose
  prompt: [task description]
  run_in_background: true

Phase 4: Monitoring

Status Polling

Poll VK every ~60 seconds during active work:

mcp__vibe_kanban__list_tasks:
  project_id: [uuid]
  status: inprogress  # or inreview, todo

Status Report Format

## Backlog Status

| Section         | Task ID | Status     | Notes            |
| --------------- | ------- | ---------- | ---------------- |
| 1. Exec Summary | 88e5... | inreview   | Ready for review |
| 2. Repo Org     | f722... | inprogress | Writing          |
| 3.1 Benchmark   | 371c... | todo       | Blocked          |

**Active**: 5/15 | **In Review**: 2 | **Done**: 8

Phase 5: Review Process

When Task Reaches inreview

1. Read the updated document section
2. Check for:
   • Accuracy against source files
   • Consistency with other sections
   • Completeness per scope
   • Proper formatting and diagrams
3. Decision:
   • Approve: Update to done, check doc consistency
   • Reject: Update to inprogress with feedback task

Rejection Feedback

Create follow-up task or update description:

## Revision Required

**Issues Found:**

- [ ] Missing architecture diagram
- [ ] Incorrect API reference in line 45
- [ ] Inconsistent terminology (use "coprocessor" not "processor")

**Action**: Fix issues and return to inreview.

Phase 6: Consistency Reviews

After each section merges to done:

1. Read entire document
2. Check cross-references between sections
3. Verify terminology consistency
4. Ensure no duplicate content
5. If issues found, create new VK tasks for fixes

Completion Criteria

Task is complete when:

• All VK tasks in done status
• No pending or in-progress tasks
• Document passes consistency review
• User confirms acceptance

Quick Reference

VK MCP Tools

| Tool | Purpose | | ------------------------- | ---------------------------- | | list_projects | Get project UUIDs | | list_tasks | View all tasks with status | | create_task | Create new section task | | update_task | Change status/description | | get_task | Get task details | | start_workspace_session | Launch agent (needs repo_id) | | list_repos | Get repository UUID |

Task Status Flow

todo → inprogress → inreview → done
                  ↘ (rejected) → inprogress

Coordinator Commands

• "Create outline for [doc]" → Phase 1
• "Delegate sections" → Phase 2-3
• "Check status" → Phase 4
• "Review [section]" → Phase 5
• "Consistency check" → Phase 6

Additional Resources

Reference Files

• references/task-templates.md - Full task description templates
• references/review-checklist.md - Detailed review criteria

Examples

• examples/design-doc-outline.md - Sample document skeleton
• examples/section-task.md - Complete task description example