Motif Development Workflow

You are running the motif workflow — a 5-stage development process. The first three stages have user approval gates. Build and Validate run autonomously.

Argument Parsing

If the first word of $ARGUMENTS is "werk", strip it and use the remainder as the task description. In the Scaffold stage, use the /werk skill for task creation instead of native task tracking tools.

Otherwise, use all of $ARGUMENTS as the task description and native task tracking tools throughout.

Complexity Assessment

Before starting, assess task complexity on a 3-point scale:

Light (quick bug fix, small tweak, config change): abbreviated research, minimal planning, 1-3 tasks
Medium (feature addition, moderate refactor, new test coverage): standard research, full planning, 3-8 tasks
Heavy (large refactor, new system, architecture change): deep research, thorough planning with tradeoff analysis, 8+ tasks

State your assessment to the user before beginning Stage 1.

Pause Point Protocol

After completing Stages 1-3, present a summary and ask:

[Stage Name] complete. [Brief summary]

Ready for [Next Stage]?

go — proceed

skip — skip next stage

redo — re-run with feedback

stop — end here

Do not auto-advance through stages 1-3. Stages 4-5 run without pausing.

Stage 1: Research

Read-only codebase exploration. Do not create, edit, or delete any files.

If a subagent capability is available (e.g., a dedicated research agent), delegate to it. Otherwise, perform research directly.

Depth Calibration:

Light: Find the 1-3 most relevant files. Check for obvious patterns. Minimize tool calls.
Medium: Map the relevant module structure, identify patterns, check test coverage, review recent git history.
Heavy: Comprehensive module mapping, dependency tracing, git archaeology, related test suites, documentation review, similar precedents.

Research Process:

Orient — project structure (package.json, Cargo.toml, pyproject.toml, go.mod, etc.; top-level directories)
Locate — find files relevant to the task
Understand — read key files to understand current implementation
Context — git history for recent changes (git log --oneline -20 -- <path>)
Patterns — coding conventions, testing patterns, architectural decisions
Toolchain — find the test, build, and lint commands so you can run them in later stages

Output:

Relevant Files — each with a 1-line description
Patterns & Conventions — how similar work is done in this codebase
Constraints — build/CI requirements, type system, linting rules
Toolchain — exact commands for test, build, lint
Risks — fragile areas, edge cases, missing coverage

Stage 2: Plan

Using research findings, produce an implementation plan.

Output:

Approach — what will change and how (be specific about the technique, not just "modify X")
Files — which files will be created, modified, or deleted
Testing — what tests to write or update, how to verify correctness
Tradeoffs (medium/heavy only) — alternatives considered and why this approach wins

Scale depth to complexity. A light plan can be a few sentences. A heavy plan needs alternatives and risk assessment.

Stage 3: Scaffold

Decompose the plan into a task list. Each task should be a single, verifiable unit of work.

Native mode — use the available task tracking tools (TaskCreate, TaskUpdate, etc.) to create and manage tasks.

Werk mode — use the /werk skill to create and manage tasks.

For both modes:

Set dependencies where order matters
Include test tasks alongside the code they verify (not as a separate "write all tests" task)
Final task: validate the overall goal

Present the task list. The user may add, remove, or reorder before approving.

Stage 4: Build

This stage runs autonomously. Work through tasks in order without stopping for approval on each one.

For each task:

Mark in-progress
Implement the change
If tests are part of this task, write and run them
Mark completed

When to stop and ask:

A task requires a design decision not covered by the plan
Tests fail in a way that suggests the plan is wrong (not just a typo)
You discover the plan missed something significant

For routine issues (lint errors, minor test fixes, small deviations), handle them and keep going. Use your judgment — the plan is a guide, not a contract.

After all tasks complete, proceed directly to Validate.

Stage 5: Validate

Run automatically after Build completes.

Goal check — does the implementation satisfy the original task description?
Tests — run the test command discovered in Research. Report pass/fail.
Diff summary — all files changed with a brief description of each change
Loose ends — anything incomplete, TODO comments added, known limitations

Present the validation report. If issues exist:

fix + details → go back to Build for targeted fixes
done → accept current state