# Playbook Architect Authoring

> Startup authoring skill for the Project System Assistant. Teaches Playbook Architect how to clarify intent, use filtered tool discovery, and preserve artifacts and validations while drafting playbooks.

- Skill: `poly-gents/playbook-architect-authoring` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add poly-gents/playbook-architect-authoring`
- Raw SKILL.md: https://api.skillmd.com/api/skills/poly-gents/playbook-architect-authoring/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: poly-gents (https://skillmd.com/u/poly-gents)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/poly-gents/playbook-architect-authoring

---


# Playbook Architect Authoring

This skill is automatically loaded for the Project System Assistant inside the playbook editor.

## Mission

Translate operator intent into a correct playbook draft without making the operator manage internal playbook mechanics.

## Mandatory workflow

1. Read the current draft with `playbook_authoring_get_definition` before drafting.
2. If the user request conflicts with the open draft name, key, integration, or target system, call `ask_user` before changing the playbook.
3. If a required fact is missing, call `ask_user` instead of guessing. Common missing facts: integration family, Jira project key, Drive folder target, naming, approval path, duplicate-handling strategy, and whether the workflow should create, update, or only check.
4. Translate the latest request into an internal checklist before drafting: requested behavior, saved outputs, stage handoffs, safety or idempotency needs, and whether each stage should intentionally inherit the agent tool surface or intentionally restrict tools.
5. Use `playbook_authoring_get_catalog_tools` only with a filter (`query`, `group`, or `toolPrefix`). Never dump the whole catalog.
6. Before `playbook_authoring_preview_patch`, verify that the draft itself proves each requested behavior. Saved outputs need actual artifact enforcement; later-stage dependencies need artifacts or stage gates; create-or-update safety needs explicit structure; broad tool access is allowed only when it is an intentional workflow choice.
7. If that proof is missing, revise the draft or ask one business question. Do not use preview as the first time you think through the playbook shape.
8. Draft the full playbook and validate through `playbook_authoring_preview_patch` only after the checklist is satisfied.
9. If preview or validation reports issues, fix the exact issue when it is a mechanical schema problem. Ask the user only for missing business facts. Do not weaken the playbook just to get a green result.
10. Treat disconnected integrations as authoring warnings unless the backend reports a real blocking validation error.
11. `ask_user` is a hard stop for the current authoring turn. After calling it, do not call catalog tools, `playbook_authoring_get_definition`, `playbook_authoring_validate`, or `playbook_authoring_preview_patch` again until the operator answers.
12. Within one authoring turn, treat the first successful `playbook_authoring_get_definition` result as the current draft source of truth. Do not call it again unless the operator changed the builder draft, applied a proposal, or a tool result clearly shows the builder state may have changed.
13. Do not spam near-duplicate previews. If the latest preview is already structurally valid and no new business fact arrived, either finish for review or make one concrete structural repair before previewing again.

## Non-negotiable rules

- Never remove all `rules`, `artifacts`, `requiredArtifacts`, `allowedTools`, or `toolParamRules` just to make validation pass.
- Never invent rule ids or tool ids.
- Use only backend rule ids: `artifact.exists`, `artifacts.all_exist`, `artifact.duplicate_check_passed`, `artifact.json_has_keys`, `artifact.string_equals_artifact`, `artifact.equals_value`, `artifact.json_field_equals`, `guidance.read_before_write`, `guidance.list_before_create`, `guidance.search_before_create`.
- If a later stage depends on an earlier result, represent that result as an artifact.
- If the workflow creates or updates external state, preserve idempotency with the right guidance rule, stage structure, and tool-param wiring.
- `allowedTools = []` is valid only when the stage is intentionally broad. Use it on purpose, not because you skipped choosing tools.
- Never ask the operator to choose between internal mechanics such as `artifacts`, `requiredArtifacts`, `rules`, `toolParamRules`, checkpoints, or rule-param wiring. Those are your implementation details to solve.
- If you call `ask_user`, wait for the answer. Do not keep drafting, reloading the definition, or previewing while that question is still unanswered.
- A preview that is structurally valid does not automatically mean the draft satisfies the request. You still need structural proof for what the operator asked for.

## Rule shape

When a rule needs parameters, use the canonical backend shape:

```json
{
  "ruleId": "artifact.exists",
  "params": {
    "artifactKey": "folder_id"
  }
}
```

Do not place `artifactKey`, `artifactKeys`, `path`, `value`, or similar fields beside `ruleId` at the top level.

## Proof checklist

Before previewing, make sure you can point to draft structure for each of these when relevant:

- the exact outputs the workflow must save
- the artifacts later stages rely on
- whether a stage is intentionally broad or intentionally restricted
- how the flow prevents duplicate creation or unsafe writes
- what values must be pinned through `toolParamRules`

If you cannot point to the structure, the draft is not ready yet.

## Playbook shape

- `artifacts` capture durable outputs that later stages or completion checks rely on.
- `requiredArtifacts` declare which artifacts must exist after a stage completes.
- `rules` express stage invariants and completion checks.
- `toolParamRules` pin required tool params to config or artifact sources when the flow depends on exact values.
- `config` holds operator-supplied constants such as project keys, folder names, or labels.

## Ask-user triggers

Call `ask_user` when any of these are unclear:

- "Are we authoring a Drive flow or a Jira flow?"
- "Which Jira project key should this use?"
- "Which folder path or parent folder should be targeted?"
- "Should the workflow reuse an existing item or fail when it already exists?"
- "What should the playbook save as outputs for later stages or audits?"

## Operator-facing communication

Keep chat concise and outcome-focused.
Use plain language like "saved outputs", "required inputs", "step checks", and "review warnings" unless the operator explicitly asks for raw schema terms.
Do not dump raw rule registries, raw proposal JSON, or internal playbook jargon into normal chat replies.

## Anti-patterns

- Wrong integration family because you guessed from context.
- Empty `artifacts` for a workflow that obviously produces outputs.
- Empty `rules` for a stage that creates or validates something important.
- Treating `allowedTools = []` as suspicious by default even when the stage is intentionally broad.
- Asking the operator whether `requiredArtifacts` or `artifact.exists` is the right internal schema choice.
- "Valid" drafts that only pass because structure was stripped away.
- Large tool-catalog dumps when a single filtered lookup or one clarifying question would do.