BluePeriod Agent Skill: Advanced Writing & Editorial

This document provides instructions for AI agents (like Claude Code) on how to effectively use the BluePeriod MCP tools to participate in the creative writing process.

1. Core Philosophy: The Deep MCP Pattern

BluePeriod follows a Deep MCP pattern. Instead of doing the writing internally using small models, the application exposes raw data and an Adit engine to you.

• You are the Brain: You analyze the plot, understand the characters, and decide on the prose.
• BluePeriod is the Body: It provides the storage, hierarchy, and the precision editing engine (Adit).

2. Working with the Hierarchy

BluePeriod organizes narrative in a strict 5-level hierarchy:

1. Parts: Large story movements (e.g., "Volume 1", "Middle Act").
2. Arcs: Story arcs within parts.
3. Chapters: Individual thematic units.
4. Stories: Scenes or specific narrative beats.
5. Sections: The smallest unit. Manuscript text is attached to Sections.

ID-based Operations

Most tools require a UUID. Always use get_raw_plot first to discover the structure and find the IDs you need.

3. The Adit Editing System

To edit a manuscript, you should prefer the Adit tools over direct overwriting. Adit uses a "Search and Replace" logic that is robust and preserves surrounding context.

Adit Structured Output (Primary Recommendation)

Use the blueperiod_apply_adit_edits tool. This is the most robust method for reflecting edits.

• thought_process: Describe your rewrite strategy (e.g., "Increasing sensory details").
• edits: An array of objects with original_snippet and new_snippet.
• Note: The original_snippet must exactly match a part of the manuscript.

Adit Delimiter Format (Flexible Alternative)

If you prefer to list multiple changes in a single diff-like text, use the blueperiod_apply_adit_delimiter tool with SEARCH/REPLACE blocks:

<<<<<<< SEARCH
Suddenly, he saw a giant dragon in the sky. It was red.
=======
A crimson shadow eclipsed the sun. He looked up to find a Great Wyrm—scales like smoldering embers—spiraling through the clouds.
>>>>>>> REPLACE

• Precision: Only include the minimum text needed for a unique match.
• Thought Process: Always include your reasoning at the top of the input text.

4. Recommended Workflow for Editorial Tasks

When assigned a writing task (e.g., "Make this scene more tense"):

1. Discovery: Call blueperiod_list_projects and verify the active project.
2. Map: Call blueperiod_get_raw_plot to find the correct section_id.
3. Context: Call blueperiod_get_plot_context for that section to understand what happens before and after.
4. Read: Call blueperiod_get_raw_manuscript to get the current text.
5. Draft: Formulate your changes in your internal thought space.
6. Apply: Call blueperiod_apply_adit_delimiter with your SEARCH/REPLACE blocks.

5. Metadata and Prompts

If you need to understand the "house style" or the author's specific intent:

• Use blueperiod_list_writing_prompts. These cards often contain world-building rules or tonal guidelines that the user expects you to follow.

6. Research

Use blueperiod_search_web and blueperiod_open_url if you need to double-check facts or find inspiration for specific details (e.g., "What kind of flowers bloom in Tokyo in April?").

Remember: BluePeriod is a Human-in-the-Loop system. The user will see a Diff of your changes and must approve them before they are permanently saved to the project. Aim for high-quality, meaningful edits.