# Playbook Update

This page explains how new content gets into the AI Playbook without anyone manually writing markdown, committing code, or managing a GitHub repository. The entire workflow is handled by a Claude Cowork automation that checks Asana for content requests, drafts pages, pushes them to a review branch on GitHub, and publishes approved content to GitBook.

***

## How It Works

The automation runs as a pair of scheduled tasks inside a Claude Cowork project. The primary task runs every day at 3:00 PM ET and checks the **AI Playbook** project in Asana for new content requests. A secondary polling task watches for approvals and handles publishing.

Here is the full workflow:

### 1. Submit a Request in Asana

To request a playbook update, create a task in the **AI Playbook** Asana project. The task will automatically land in the **Ready for Playbook** section. The task description must include four fields:

* **Location**: Where the content belongs in the playbook hierarchy (e.g., "Claude Skills > Overview")
* **Content Type**: One of three options: **New Page**, **Edit Existing**, or **Add to Existing**
* **Context**: What the content should cover, with enough detail for Claude to write a complete draft
* **Follow-up Needed**: Any questions that need to be answered before drafting can begin. Write "None" if the request is ready to go

The more context you provide, the better the first draft will be.

### 2. Claude Picks Up the Task

At the scheduled time, Claude reads every incomplete task in the Ready for Playbook section. For each task, it reads the name, description, and all comments to understand what is being requested.

### 3. Draft or Follow Up

What happens next depends on whether the task has enough context:

**If Follow-up Needed is "None"**, Claude drafts the content immediately. It reads the existing playbook files to match the current structure, voice, and formatting. It writes the markdown file to the correct location in the repository, updates the table of contents and changelog, and pushes everything to the **drafts** branch on GitHub. Claude then comments on the Asana task with a summary of what was drafted and a direct link to the file on the drafts branch so the team can review it.

**If Follow-up Needed contains questions**, Claude does not draft anything. Instead, it comments on the Asana task with the specific questions that need answers. Once those questions are answered in the task comments, Claude will pick up the task on its next scheduled run.

### 4. Human Review

Claude never publishes content without explicit approval. After pushing a draft to the **drafts** branch, a polling task activates and checks the Asana task comments every five minutes for a response. The reviewer can approve the draft, request changes, or reject it.

To approve a draft, reply to the Asana task with something like "approved," "push it," or "ship it." To request changes, describe what needs to be revised in a comment. Claude will update the draft and push the revisions back to the drafts branch.

### 5. Publish to GitBook

Once approved, Claude merges the drafts branch into **main**. GitBook syncs automatically after each push to main, making the content live on the playbook site. Claude then comments on the Asana task confirming that the content is live and where it can be found in the playbook.

***

## The Drafts Branch

All drafted content is pushed to a dedicated **drafts** branch on GitHub rather than directly to main. This keeps unpublished content separate from the live playbook and creates a clean review step before anything goes live.

The drafts branch is reset to match main before each new draft is pushed. This means the branch always represents the difference between the current live playbook and the proposed changes. Once a draft is approved and merged, the cycle starts fresh.

You can review pending drafts at any time by viewing the drafts branch on GitHub: `https://github.com/themailworks-ai/ai-playbook/tree/drafts`

***

## What Powers the Automation

This automation runs inside a Claude Cowork project with the following components:

| Component                  | Role                                                                                                                |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Cowork Project**         | The workspace where the automation lives, with custom instructions that define writing standards and workflow rules |
| **Asana Connector**        | Allows Claude to read tasks, parse descriptions, and post comments directly in Asana                                |
| **GitHub Repo**            | The source of truth for playbook content, synced to GitBook on every push to main                                   |
| **Daily Scheduled Task**   | Runs at 3:00 PM ET to check Asana for new content requests and draft pages                                          |
| **Polling Scheduled Task** | Runs every 5 minutes (when active) to watch for approvals and handle publishing                                     |
| **Custom Instructions**    | Detailed rules covering voice, tone, page structure, formatting, git workflow, and the review process               |

### The Custom Instructions

The custom instructions are the backbone of this automation. They tell Claude exactly how to behave at every step, including:

* **Writing standards**: Voice, tone, heading hierarchy, formatting rules, and content patterns
* **File structure rules**: Where to place new files, how folders map to GitBook groups, and how to update the table of contents
* **Git workflow**: Push drafts to the drafts branch for review, merge to main only after explicit approval
* **Review process**: Never push to main without approval, use the polling task to watch for responses
* **Asana integration**: How to parse task descriptions, when to draft vs. ask follow-up questions, and what to comment at each stage
* **Changelog**: Every content push includes a versioned changelog entry

***

## How to Set This Up From Scratch

If you wanted to replicate this automation for a different playbook or documentation site, here is what you would need:

1. **A GitBook site synced to a GitHub repository.** GitBook handles the hosting and rendering. GitHub holds the markdown source files. The GitHub repo should also be cloned to your local machine, since Cowork works with local files. The Cowork project folder points to this local clone, and all reads and writes happen on disk before being pushed to GitHub.
2. **An Asana project** with a section designated for incoming content requests. Tasks in that section follow a structured description format so Claude can parse them programmatically.
3. **A Claude Cowork project** with the local repo clone connected as the project folder and the Asana connector enabled.
4. **Custom instructions** that define the writing standards, file structure, git workflow, review process, and Asana integration rules.
5. **Two scheduled tasks** inside the Cowork project: one that runs the daily Asana check and drafts content, and a polling task that watches for approvals and handles merging to main. The polling task stays disabled until a draft is posted, then activates automatically and deactivates once the review cycle completes.

The entire setup lives inside Cowork. No external CI/CD pipelines, no webhook servers, no additional infrastructure.

***

## Current Limitations

* **Scheduling requires the desktop app to be open.** Scheduled tasks only run while the Claude Desktop app is running and the computer is awake. If the app is closed at the scheduled time, the task will not run until the next scheduled window.
* **No image generation.** Claude cannot create screenshots or visual assets. Pages that need images include placeholder markers for a human to fill in.
* **Single reviewer.** The current workflow routes all reviews through one person. This could be expanded in the future by using Asana task assignments to route reviews to different team members.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://knowledge.themailworks.com/claude-cowork/playbook-update.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.