workflow-patterns

Overview of workflow-patterns skill

What workflow-patterns actually helps with

The workflow-patterns skill is a process skill for executing implementation work in a strict, test-driven sequence. It is designed for Conductor-style task delivery: pick the next planned task, mark status in plan.md, write failing tests first, implement in small increments, verify at checkpoints, and keep commits aligned to task state. If you want an agent to follow a disciplined delivery pattern instead of jumping straight to code, this is what workflow-patterns is for.

Best fit for this workflow-patterns skill

This workflow-patterns skill fits teams or solo builders who already organize work in task plans and want more reliable execution from an AI agent. It is especially useful when you care about:

• preserving task order by phase
• enforcing red-green-refactor behavior
• keeping progress recorded in plan.md
• separating status commits from implementation commits
• running verification before declaring work complete

If your repo already has planning artifacts and tests, the skill is much more valuable than a generic “implement this feature” prompt.

The real job-to-be-done

Most users are not looking for theory about TDD. They want an agent that can take a planned task and complete it without skipping workflow controls. The real job is: turn a checked-box task list into a repeatable implementation loop with fewer missed tests, fewer ambiguous handoffs, and clearer progress tracking.

What makes workflow-patterns different from a normal coding prompt

A normal prompt often produces code first and process second. workflow-patterns inverts that. It gives the agent a task lifecycle with explicit checkpoints:

1. choose the next pending task in order
2. mark it in progress
3. write failing tests
4. implement until tests pass
5. refactor
6. run verification
7. update task status and commit appropriately

That structure matters if your biggest risk is not code generation, but uncontrolled execution.

Important limits before you install

This skill is narrow by design. It does not provide framework-specific implementation rules, test libraries, or repo-specific commands. It assumes you can supply those. If your project has no plan.md, weak test coverage, or no appetite for small disciplined commits, workflow-patterns for Workflow Templates may feel too rigid.

How to Use workflow-patterns skill

How to install workflow-patterns skill

Install from the wshobson/agents repository:

npx skills add https://github.com/wshobson/agents --skill workflow-patterns

After install, invoke it when you want the agent to follow the repository task lifecycle rather than freestyle implementation.

Where this skill lives and what to read first

The skill is located at:

plugins/conductor/skills/workflow-patterns/SKILL.md

Read SKILL.md first. For this skill, that file is the source of truth and contains the full workflow. There are no extra support folders here, so your main adoption task is understanding the sequence and adapting it to your repo conventions.

What inputs workflow-patterns needs to work well

The skill becomes much more useful when you provide concrete execution context:

• path to plan.md
• current phase or milestone
• the exact task ID to consider, or permission to select the next [ ] item
• test command
• lint/typecheck/build commands
• branch or commit policy
• any repo constraints such as “do not edit generated files”

Without these, the agent may understand the process but still guess at how your project verifies work.

The minimum prompt that can invoke workflow-patterns well

A workable starting prompt looks like this:

Use the workflow-patterns skill.

Project plan: docs/plan.md
Follow tasks in order and do not skip phases.
Select the next pending [ ] task, mark it [~], and keep status updates separate from implementation commits.
Use TDD: write failing tests first, then implement, then refactor.
Verification commands:
- pytest
- ruff check .
- mypy .
When complete, update the task to [x] only if verification passes.

This is already better than “implement the next feature” because it supplies task source, ordering, verification, and completion criteria.

How to turn a rough goal into a strong workflow-patterns prompt

Weak goal:

Implement the next task with workflow-patterns.

Stronger goal:

Use the workflow-patterns skill for docs/plan.md.

Current target phase: Phase 2 only.
Select the next unchecked task in order.
Before coding, change that task from [ ] to [~].
Write failing tests covering happy path, edge cases, and one error path.
Use these commands:
- npm test -- --runInBand
- npm run lint
- npm run typecheck
Do not modify unrelated tasks.
When all checks pass, refactor if needed, update plan.md to [x], and summarize what changed.

The stronger version reduces the biggest adoption risk: the agent knowing the workflow but not your local constraints.

The expected task lifecycle in practice

The core workflow-patterns usage pattern is:

1. inspect plan.md
2. choose the next pending task in the current phase
3. mark it [~]
4. commit or at least isolate that status change
5. write tests that fail
6. implement the minimum change to pass
7. refactor safely
8. run verification
9. mark the task [x]
10. complete final commit notes and summary

This matters because the skill is built around state transitions, not just code edits.

Why plan.md quality directly affects output quality

This skill is only as good as the plan it executes. Vague task text like “improve auth flow” leads to vague test targets and weak completion logic. Strong tasks are specific enough to test:

• files or modules affected
• expected behavior
• error conditions
• acceptance checks
• dependencies on previous tasks

If your plan.md is thin, improve that before judging the workflow-patterns guide.

How to handle verification commands

The skill emphasizes a verification protocol, but it does not know your commands by default. Always provide exact commands and failure policy. For example:

Verification must pass before task completion:
- cargo test
- cargo clippy -- -D warnings
- cargo fmt --check

If any verification step fails, do not mark the task complete.

This prevents the common failure mode where the agent says the task is done after only partial testing.

Commit handling and status tracking

A practical benefit of workflow-patterns install is better repo hygiene when using AI. The skill explicitly treats status updates and implementation work as separate events. That helps when you want:

• visible task progress in version control
• cleaner reviews
• easier rollback of workflow metadata versus code
• less ambiguity about whether work is truly in progress or complete

If your team does not want separate commits, say so up front and ask the agent to preserve the status transitions without splitting commits.

When to adapt the workflow instead of following it literally

Use the sequence as a control system, not a religious rulebook. Adapt it when your environment differs:

• monorepos may need package-scoped test commands
• legacy repos may need characterization tests first
• prototypes may prefer fewer commits but still keep [ ] → [~] → [x]
• hotfixes may justify narrower refactor steps

The key is to preserve the checkpoints that reduce risk, especially test-first work and explicit verification.

workflow-patterns skill FAQ

Is workflow-patterns only for Conductor users?

No, but it is clearly shaped by Conductor-style planning and TDD. You can use workflow-patterns outside that ecosystem if you have an equivalent plan file, task order, and verification routine. Without those, the skill loses much of its advantage.

Is this better than a normal prompt for feature work?

Yes, when the main problem is execution discipline. A normal prompt may generate acceptable code, but it often skips task ordering, progress updates, and test-first behavior. workflow-patterns usage is better when consistency and traceability matter more than speed alone.

Is workflow-patterns beginner-friendly?

Moderately. The process is easy to follow, but beginners may struggle if they lack:

• a clear plan.md
• confidence writing failing tests first
• project-specific verification commands
• understanding of small, reviewable commits

If you are new to TDD, start with a single well-scoped task rather than a whole phase.

When should I not use workflow-patterns skill?

Skip it when:

• you do not maintain task plans
• you need exploratory coding more than controlled execution
• the repo has little or no test infrastructure
• you want the agent to brainstorm architecture, not complete queued tasks
• the work is too small to justify status and verification overhead

In those cases, a lighter implementation skill or direct prompt may be a better fit.

Does workflow-patterns include repo-specific commands or automation?

No. The repository evidence shows this skill is essentially documentation in SKILL.md, not a package with helper scripts or rule files. Its value is the execution pattern. You supply the operational details.

Can workflow-patterns help with incomplete or messy plans?

Only partly. It can enforce order and state changes, but it cannot invent good acceptance criteria from a vague backlog item. If task definitions are weak, improve the plan before expecting strong outputs.

How to Improve workflow-patterns skill

Give workflow-patterns stronger task definitions

The fastest way to improve results is to upgrade task wording. Good tasks for this skill include behavior, constraints, and finish lines. For example:

Weak:

- [ ] Improve validation

Better:

- [ ] Task 2.1: Reject invalid email formats in user registration, return 400 with field-level error, and add tests for valid, invalid, and missing email cases

That single change gives the agent a clearer basis for red tests, implementation scope, and verification.

Provide exact commands, not generic “run checks”

Many failures in workflow-patterns usage come from underspecified verification. Replace “run tests and lint” with exact commands and any required environment details. If tests need a service, fixture, or package filter, include that too.

Tell the agent how strict to be about task order

The skill defaults to sequential execution within the current phase. If your real workflow allows exceptions, state them. Otherwise the agent may either skip too much or refuse useful work. Clear policy improves reliability:

Do not skip tasks unless blocked by missing infrastructure.
If blocked, stop and report the blocker instead of jumping ahead.

Add repo-specific TDD guidance when the project is legacy-heavy

In mature repos, pure red-green-refactor may need interpretation. If test harnesses are slow or architecture is tangled, tell the agent how to apply the pattern:

• prefer characterization tests before refactors
• limit scope to touched modules
• avoid broad cleanup in the same task
• capture known flaky tests separately

This keeps workflow-patterns practical rather than dogmatic.

Prevent common failure modes

The most common problems are predictable:

• marking tasks complete before all checks pass
• writing tests after implementation
• editing multiple tasks in one pass
• skipping the [~] in-progress state
• mixing workflow metadata and feature work without clarity

Call these out in your prompt if they matter to your team.

Ask for structured end-of-task reporting

To make the skill more useful in daily work, ask the agent to finish each task with a compact report:

• selected task
• tests added or updated
• implementation summary
• verification results
• plan file status changes
• blockers or follow-ups

This turns workflow-patterns guide output into something reviewers and future sessions can trust.

Iterate after the first run instead of replacing the skill

If the first result is awkward, do not assume the workflow-patterns skill is weak. Usually the issue is missing execution context. Improve inputs in this order:

1. clearer task text
2. exact verification commands
3. allowed scope and file constraints
4. commit/status policy
5. blocker handling rules

Once those are supplied, the skill is much more likely to produce controlled, high-confidence task execution.