Turning Cross‑Project Prompts into a Structured AI Workflow with OpenSpec

When the author first opened requirement-pipeline.yaml, the relief was not about another automation script but about finally capturing the most annoying part of cross‑project requirements in a workflow.

Typical pain points include unclear requirements, fuzzy project boundaries, unknown interface change order, and AI developers diving into code only to discover the direction was wrong. In a workspace with multiple projects (server, admin, web, worker, scripts), these steps are usually kept alive by human memory, which inevitably fails.

The OpenSpec workflow named requirement-pipeline (version 0.3.0) is explicitly positioned as a cross‑project requirement pipeline with clarification interaction. It does not aim to make AI “more powerful” but to make it “slower” by forcing a sequence of steps: clarify, split, confirm, execute, and wrap‑up.

Step 1 – clarify_first

The step name itself is a clue: the AI pretends to be a product manager + senior engineer, reads the requirement, existing documentation, and each project's CLAUDE.md, then decides whether any critical question would block decomposition. The prompt explicitly tells the model not to ask trivial details (e.g., button colour, wording). It focuses on four hard issues:

Unclear key business rules

Ambiguous interface contracts

Conflicts with existing architecture that require a technology choice

Unspecified performance or compatibility requirements

If no blocking question exists, the model outputs an empty JSON array; otherwise it returns a structured JSON object containing id, question, context, type and, for multiple‑choice items, options:

{
  "questions": []
}

This JSON becomes part of the requirement context ( ${requirement_clarifications}) for later stages, turning what would be a fleeting chat into a concrete pipeline input.

Step 2 – split

Only after clarification does the workflow start splitting. The prompt asks the model to produce the “minimum necessary” sub‑tasks per project, using the phrase “minimum necessary” deliberately. Each sub‑task is represented as a ProjectTask object with fields:

id

project

title

description

dependsOn

The dependsOn field is crucial because front‑end tasks depend on back‑end APIs, admin tasks depend on server fields, and worker tasks depend on configuration data. Missing these dependencies would cause parallel sessions to clash later.

The split result is not executed directly; it is handed to the next step, confirm, for human verification.

Step 3 – confirm

Human reviewers quickly check the generated task list and boundaries. Skipping this step often leads to wasted effort when code is written for the wrong project.

Step 4 – execute_tasks (fan‑out)

After confirmation, the workflow fans out: each ProjectTask spawns an independent Claude session with project: "${item.project}". Each session receives:

Current project name and path

Sub‑task title and detailed description

Overall requirement context

Answered clarification questions

Additional reference documents

The session must:

Read the project's CLAUDE.md Make the minimal necessary code changes

Run lint and tests (as declared in workspace.yaml)

Summarize which files changed and why

Two notable configuration knobs are: additionalDirs: ["../"] – lets a session read other projects in the workspace, useful for contract verification. allowedTools – restricts the model to Read, Write, Edit, Grep, Glob. No arbitrary external commands are permitted.

The workflow also sets permissionMode: bypassPermissions, which removes permission checks for speed but requires sandboxing, permission whitelists, or CI gates in production environments.

Step 5 – wrap_up

The final step performs a cross‑project review. It runs git status and git diff from the workspace root, checks interface‑contract consistency (e.g., front‑end tag_id vs back‑end tagId), and generates a PR description draft segmented by project, each containing Why, What, and How‑to‑test sections.

This step is essential because many bugs arise from mismatches between projects rather than within a single repository.

Who Should Use This Workflow?

Monorepos or pseudo‑monorepos where a workspace contains backend, admin console, front‑end, scripts, SDK, etc.

Teams that have adopted AI coding agents and now face increased review pressure.

Organizations where requirements are scattered across documents (DingTalk, ZenTao, Wiki) rather than a single source.

It is not suitable for tiny changes (e.g., a single typo) or exploratory redesigns that need upfront architectural review.

Common Pitfalls

Too many clarification questions – tighten the prompt to only ask questions whose answers would change the split direction.

Unstable JSON output – ensure the model ends the message with a pure JSON code block and no trailing text.

Sequential execution ( concurrent: false) – safe but slow; enable concurrency only when tasks are truly independent. stopOnError: true – halts the whole pipeline on a single project failure; acceptable for dependent tasks but wasteful for independent ones.

Test commands hidden in prompts – better to read them from workspace.yaml or pass them as structured variables.

Overly permissive bypassPermissions – use sandboxed worktrees or containers for production use.

Contract checks still rely on natural‑language review – consider adding OpenAPI diff, type‑generation checks, or contract tests.

Suggested Improvements

Add a dry_run mode that runs only clarify_first, split, and confirm to produce a lightweight review artifact.

Include risk grading in the split output ( risk: low|medium|high) and a testSuggestion field for high‑risk tasks.

Make the execution report structured JSON (changed files, test results, remaining items, risk points) so wrap_up can aggregate accurate PR drafts.

These modest changes turn the pipeline from “can run” to “can be operated at scale.”

Conclusion

The OpenSpec requirement-pipeline.yaml workflow scores high not because it uses exotic technology but because it codifies the timeless engineering steps of clarification, decomposition, confirmation, execution, and retrospection. By solidifying these judgments into a repeatable pipeline, teams prevent AI from becoming a “faster rookie” that rushes ahead without proper process, and instead let AI act as a disciplined coding assistant.