init-workflow

Every other skill in this plugin reads .claude/workflow.json. This skill writes it.

0. If the config already exists, this is a re-run

Read .claude/workflow.json and .claude/workflow.env before anything else. When either is there, the owner has already answered - never re-ask from scratch and never silently overwrite.

Run the detection in step 1 anyway, then report both files' current values beside what you found, and ask a single question: keep the config as it stands, or change it.

Preserve every field you were not asked to change, including any the owner hand edited after the last run. Write the file only once the answers are in.

1. Detect, do not assume

Find diagram candidates with git ls-files, not find - it already excludes build output, dependencies and the untracked worktree copies that otherwise triple the count:

git ls-files '*.excalidraw' '*.drawio' '*.mmd' '*.d2' '*.puml'

decisions - detect only

decisions.adrDir is where a hard decision goes when it is worth keeping past the plan folder, and decisions.glossary is the doc whose vocabulary the plan should use. Both are pointers to places the repo already has:

git ls-files | grep -iE '(^|/)(adr|decisions)/|(^|/)(CONTEXT|GLOSSARY)\.md$'

Record what you find and omit what you do not. Creating an ADR folder for a repo that does not keep one is a practice decision, and it belongs to the owner - say in your report that the key is unset and what that costs: a hard decision made during a plan lives only in the gitignored plan folder and is lost with it.

Where plans live - ask

The rule is in plan-start's Where plans live. The repo folder stays the default source of truth; a vault is the owner's choice. List the vaults this machine knows:

jq -r '.vaults[].path' "$HOME/Library/Application Support/obsidian/obsidian.json"

Ask with its own AskUserQuestion call, one option each:

• the repo folder - projectsDir from above - labelled (Recommended);
• each vault found - label the folder basename, description the path. With no obsidian.json, offer none;
• an absolute vault path, typed through Other.

On a vault, a follow-up asks the path inside it, default taskflow/<repo-name>.

Then tell the owner how the Obsidian setup works, in a few lines:

• .claude/workflow.env holds the machine-specific keys and is never committed; projectsDir in workflow.json keeps the repo folder.
• TASKFLOW_PLANS_SOURCE picks the source of truth - repo unless it says obsidian. Only that source is read.
• Plan files in the vault are written by absolute path, which prompts every time. Adding the vault to permissions.additionalDirectories in .claude/settings.local.json stops that - offer to do it.

2. Ask which model takes each tier

Every task in a plan declares a difficulty tier, and the tier binds the runner: whoever takes the task switches to that model first. So the mapping has to be the repo owner's decision, not yours - it is their cost and latency budget.

Ask before writing the config. One AskUserQuestion call carries all four questions - these three plus step 3's - so the owner answers once. Put the recommended option first and label it (Recommended). On a re-run (step 0), ask only the questions being changed, and make the current value the first option labelled (current).

Say what each choice costs in the option description, so the answer is informed:

• deep → opus - the default. Reach for sonnet here only in a small or low-risk repo where nothing crosses module boundaries.
• surface → sonnet - moving this to opus is the common upgrade for a repo with strict standards; moving it to haiku reliably produces work that fails the standards review.
• mechanical → haiku - safe precisely because the gates, not the model, decide whether the task is done. If the repo has no unit suite, there are no gates to lean on: recommend sonnet instead and say why. Offer a Codex model, such as gpt-6-luna, only when the Codex plugin is installed: the tier then runs through codex:codex-rescue, gate-runner included.

The 🙋 human tier is fixed and takes no model - a merge, a login, a credential. It exists so those steps are tracked rather than assumed.

The mapping drives this plugin's agents too, not just task rows: plan-architect and standards-reviewer run on deep, docs-diagram-auditor on surface, gate-runner on mechanical. So an answer here is a standing cost decision, not a per-task one.

Four questions is the cap on one AskUserQuestion call, and the three tiers plus step 3 fill it. So one thing you cannot infer needs a second, separate ask: which subsystem makes a task deep in this repo. Propose the answer from what you read (the module with the most cross-cutting state, the one the tests mock everywhere) and let the owner correct it - a plain question in your reply is enough, it does not need its own tool call. It goes into the CLAUDE.md section as the 🧠 row's scope.

If the owner dismisses either ask, take the recommended options, say in your report that you did, and name the file to edit. Do not stall the setup on it.

3. Ask whether this repo keeps diagrams

A diagram is a real maintenance cost, and a repo that will not pay it is better off with none than with a stale one. So the owner decides - not you, and not the mere presence of a file.

Ask, recommending by what you found in step 1:

When they are kept, two more values follow from the format rather than from another question - state which you inferred:

• format: excalidraw, drawio, mermaid, d2, plantuml.
• editedBy: human for canvas formats (excalidraw, drawio) - an agent can read labels but a text edit changes no layout, so it overflows the box. agent for text formats (mermaid, d2, plantuml), which diff and render like source.

If they choose None, say plainly what turns off: docs-sync skips its diagram section, and the docs-diagram-auditor agent checks prose only.

4. Ask the pull-request conventions

Every pull request this workflow opens carries a branch name, a title, labels and an assignee, and a repo that already has a house style rejects one that ignores it. Those conventions are the owner's, so ask - but read the history first, so each question carries the answer the repo already gives:

gh pr list --state merged -L 30 --json title,headRefName,labels,assignees
gh label list -L 100 --json name
git branch -r --format='%(refname:short)' | head -40

Without gh or a GitHub remote, read the branch names alone and say the rest went undetected.

Then look for a stacking tool. A stack is a chain of pull requests, each based on the one below it, that the tool rebases and submits together:

Another stacking tool in use - spr, ghstack, Sapling - is recorded by name with the commands the owner gives you. A tool installed but never configured for this repo is not in use.

A second AskUserQuestion call carries the first four questions, and a third carries what follows from them - the cap is four per call. Recommend what the history shows; when it shows nothing, recommend the plain option.

The third call:

{ticket} in a prefix is a placeholder: the plan records each pull request's ticket, and a pull request without one gets a question at its first task. A prefix that is the same on every pull request is written literally.

Say what the parallel answer costs in its option. The subagents' work runs at once, but every owner stop - the sitting and the hard stops after it - stays in the main session, one pull request at a time. It saves wall time on the writing and the gates, not attention.

On a re-run, ask only the conventions being changed, the current value first and labelled (current). If the owner dismisses an ask, take the recommended options and say so in the report.

5. Write .claude/workflow.json

examples/workflow.example.json is the shape. Every value in it is a placeholder - replace all of them with what steps 1 to 4 found. On a re-run, start from the file that is already there and change only the fields step 0 settled. Record the model answers as the aliases the harness accepts, or as the Codex model id when a tier runs on Codex:

"models": { "deep": "opus", "surface": "sonnet", "mechanical": "haiku" }

Leave projectsDir as step 1 found it, whatever the plan source.

On a vault choice, write .claude/workflow.env with only the keys plan-start allows: TASKFLOW_PLANS_SOURCE=obsidian, TASKFLOW_OBSIDIAN_VAULT=<basename> for a listed vault whose basename no other vault shares, or TASKFLOW_OBSIDIAN_VAULT_PATH=<path> for a typed one or a shared basename, and TASKFLOW_OBSIDIAN_PATH=<inner path>. On a re-run, change only the keys asked about; moving back to the repo sets TASKFLOW_PLANS_SOURCE=repo and keeps the vault keys. Make sure .claude/.gitignore exists and lists workflow.env.

Write "aiSignature": false unless the owner asked for AI attribution in commits. It is the switch for every Co-Authored-By trailer and "Generated with" line the workflow writes, and a missing key means false.

Gitignore the per-project plan folders - skip this for a vault source, which is outside the repo. Plans are working documents: committing them invites code and commit messages to cite them, and a citation to a gitignored file points at nothing.

The negation is per file, not per folder, so list every committed file that lives under projectsDir - the templates, and any flow or convention doc kept there. Check with git ls-files <projectsDir> before writing the rule, and verify it after with git check-ignore -v <a committed doc>, which must print nothing.

<projectsDir>/
!<projectsDir>/examples/
!<projectsDir>/examples/SCOPE.md
!<projectsDir>/examples/TASKS.md
!<projectsDir>/examples/QUESTIONS.md
!<projectsDir>/examples/PROGRESS.md
!<projectsDir>/<any other committed doc>

Skip the whole step when projectsDir is already ignored - re-running this skill must not append a second copy of the rule.

6. Put the workflow section in CLAUDE.md

Read CLAUDE.md first. A repo that already describes a workflow gets reconciled, not appended to - a second, subtly different account of the cycle is worse than none, because a reader has no way to tell which one binds.

Fill in the detected commands, the answers from steps 2 and 3, and the docs the repo actually has. Drop the diagram line when diagrams are off. Do not restate the plugin's skill bodies - CLAUDE.md carries the repo's rules, the plugin carries the procedure.

7. Enforce what prose cannot

A prose invariant rots the first time someone edits without reading it.

• Dependency direction - if the repo has directional layers, add the lint rule that fails the import (no-restricted-imports or the equivalent), rather than a paragraph asking for it.
• Commit and command discipline - the plugin's hooks stop and ask the owner before --no-verify, git add -A, bare npx-style invocations of the gate binaries, branch deletes/renames, force pushes and any other git force flag. A git force flag is refused outright unless the call's description says why force is needed. Confirm they are active with /hooks.

Report the tier mapping, the diagram decision and the pull-request conventions that were chosen, which gates were detected, which were missing, where plans live, and what you gitignored.