Start a New Workflow

You are creating a persistent workflow state file. This file survives compaction, session ends, and /clear — the work can always be resumed from it, by you, a teammate, or a fresh agent reading the repo.

The loop this starts: start → the work (done however you work by judgment; the main session always has the Agent tool) → review gate (/perdure:verdict) → close/archive. One loop, every task shape.

Not a Dynamic Workflow. Claude Code's built-in Dynamic Workflows (ultracode) are ephemeral in-session scripts; this skill creates a durable state file that persists across sessions. The two compose — a Dynamic Workflow can be the execution engine inside a tracked workflow.

Arguments

• $1 — the workflow slug (lowercase, hyphens). Example: add-jwt-refresh-tokens.
• If absent, derive one from the task in context. Never ask for it.

Steps

1. Write the plan and the decisions before touching code

From the request as it stands, draft three things:

• The plan, as checkboxes: the deliverables the user named, one per line, including the tests and the docs when the request asks for them.
• The decisions the request already settles: the constraints it fixes, the approaches it rules out, and why.
• The first next step — the resume point a fresh session would start from.

Do this before the first edit; for planning or a review, as soon as a decision is reached. If you cannot plan yet, the first item is the exploration itself and the second is "write the plan from what exploration shows". Never leave the scaffold placeholder lines: a placeholder plan is a lint finding (placeholder) and the closer refuses to close over it.

A record whose plan was never written exists but carries nothing: a session resuming from it reads a goal and starts over.

2. Create the workflow file

The canonical schema (frontmatter keys, recommended sections, statuses, commit policy) is docs/RECORDS-CONVENTION.md in this plugin, also at references/RECORDS-CONVENTION.md beside this SKILL.md in a skills-CLI install — defer to it. Concretely:

mkdir -p perdure/workflows

When the session's folder is the home folder, this is ~/perdure/workflows/: the notes stay in ~/perdure, and the report says so.

Write perdure/workflows/<YYYY-MM-DD>-<slug>.md:

---
workflow: <slug>
status: in-progress
started: <ISO 8601>
updated: <ISO 8601>
---

# Goal
<1-3 sentences, derived from the request in context; never ask>

# Plan
- [ ] <the plan items from step 1 — never the scaffold placeholder>

# Findings

# Decisions
- <the decisions from step 1, if the request settles any>

# Files modified

# Open questions

# Next step
<the first next step from step 1>

# Review
<empty until the review gate runs>

# Outcome

If the file already exists, never overwrite it: when it is this task's record, continue in it (/perdure:continue <slug>); otherwise derive a different slug.

These sections are the recommended shape, not a validation gate — real workflow files are freeform markdown, and that's fine. Update at checkpoints, not every turn.

Workflow files are committed by default — they are the context a checkout carries for whoever picks the work up next. (Archives are the opt-in privacy layer, not these.)

3. Report

Say it in one passing line, then go on with the work. Never ask whether to keep the record.

Record opened: perdure/workflows/<date>-<slug>.md (/perdure:continue <slug> resumes it)

In the home folder, the line names ~/perdure:

Record opened in ~/perdure, since this session runs in your home folder: ~/perdure/workflows/<date>-<slug>.md (/perdure:continue <slug> resumes it)

At the project's first record (no other record under perdure/workflows/), add one line: To see the resume, start a fresh session (or /clear) and run /perdure:continue.

With someone who does not code, say "note" for record and "where we left off" for the resume. At the first note in a folder outside a repository, add, to them only: "These notes are plain files in this folder; anyone who can open it can read them. Tell me what is confidential and I'll leave it out."

4. Before you call the work done

Run /perdure:verdict <slug> first. Tests and type-checks are necessary but not sufficient; the reviewer catches what they miss. The verdict lands in # Review, and an empty # Review on a completed record is a gate violation. To skip consciously, record Review: skipped — <reason> in its place; the skip becomes part of the record. A plan that is dropped is closed as abandoned, with one line on why. The closer's --abandon "<why>" also records that line as the review skip.

Autonomous / zero-turn creation

For claude -p, cron, or CI flows where the file should exist deterministically before any model turn:

(${CLAUDE_PLUGIN_ROOT} is the plugin directory, set by Claude Code. Without it, the same scripts sit in the plugin checkout's root scripts/ directory (a Codex install keeps the whole checkout), in scripts/ beside this SKILL.md (a skills-CLI install), or in your clone of github.com/arbelh/perdure.)

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/new-workflow.py" <slug> --goal "<goal>" \
  --plan "<item>" --plan "<item>" --decision "<text>" --next "<first step>"

Same schema, no model involvement, refuses to overwrite (exit 2 if exists). --plan and --decision repeat. Left out, --plan keeps the placeholder line and the script says so on stderr — the lint then reports it as placeholder.

Safety rules

• Never overwrite an existing workflow file
• Single writer during active work; updates at checkpoints, concise entries
• Idempotent: same slug twice → detect and refuse