pipeline

keel workflow orchestrator

Top-level orchestrator providing 8 pipeline entry points, reducing the cognitive burden on users facing 13 atomic skills.

Language rules

• Support questions in Chinese and English
• Reply in Chinese uniformly

Positioning

用户 → /pipeline → 自动路由到合适的 skill 组合
                         ↓
              取代手动选择 13 个原子 skill

Core value: users only need to say "what I want to do"; the pipeline handles "which skills to use, in what order."

Quick start

One sentence: Don't know which skill to use? Start here and it will automatically route to the correct workflow.

Most common usages: /pipeline(automatic judgment),/pipeline init(new project),/pipeline feature(add feature)

Not suitable? Known target skill → call directly /requirements、/feature、/bugfix etc.

Route announcement (mandatory)

After selecting the entry point andbefore delegating to the first skill, first announce three lines:

路由：<入口名>            ← 依据：<阶段检测命中的那一条>
链路：skillA → skillB → skillC
排除：<最接近的另一个入口> —— <一句话为什么不是它>

Only after the announcement begin delegation. ⛔ Do not run and talk at the same time.

Why mandatory: the cost of a wrong route only becomes apparent after the chain finishes running, and by then documents and commits have already been produced. The announcement moves the error-correction point earlier to a zero-cost position—the user can tell at a glance whether the route went wrong. It also turns "silent skipped steps" into an observable absence: once the chain is declared, a missing step is visible.

Detailed documentation

• Shared constraints SSOT:../shared/constraints.md
• pipeline governance SSOT:references/realign.md

This skill follows the shared constraints SSOT: gating markers, yaml-summary-v1, Task delegation, user confirmation, Recovery format, read-only / dry-run, FUTURE tri-state, realign / spec_version see skills/shared/constraints.md. This file only describes pipeline orchestration private rules.

Run modes / entry syntax

/pipeline                → 提问式调度（自动判断）
/pipeline init           → 新项目全流程
/pipeline feature        → 新功能开发（自动检测 Harness 深度）
/pipeline bugfix         → Bug 修复
/pipeline verify         → 质量检查
/pipeline close          → 周期收尾
/pipeline insights       → 外部洞察吸收
/pipeline design         → 设计稿到达/更新（主动推送）
/pipeline realign        → 规范升级入口（统一 realign 维度）

The tier and level of detail are determined by natural language, normalized by the orchestration layer and passed down (task/intent-normalization); users do not need to remember parameters.

realign parameter syntax

/pipeline realign [--scope=<spec|prd-mapping|health>] [--target=<path>] [--dry-run|--apply] [--fix=<rule_id>]
/pipeline realign --no-realign

Parameter	Description
--scope=spec	Default; handles the spec_version dimension
--scope=prd-mapping	Handles the PRD mapping dimension
--scope=health	Proactive documentation health review (3 dimensions / health-lint rule, checklist see references/health-lint-implementation.md), execution interface see references/realign-scope-health.md
--target=<path>	Limit rescan target path
--dry-run	Only produce a gap report,zero writes to business artifacts; scope=health allows writing .health-report.md as the report carrier
--apply	Execute confirmed migration / completion actions
--fix=<rule_id>	Only scope=health; only fix violations of the specified rule (must be paired with --dry-run or --apply; if not paired, treated as --dry-run）
--no-realign	Reject upgrade prompt, required when writing .devdocs-realign-ack（--headless )

Question-based dispatch (intelligent guidance)

When called without parameters, converge to the appropriate entry point through phase awareness + intelligent guidance:

Phase detection

First scan docs/devdocs/ actual files (rather than relying on 00-context.md progress), and route by the first match in the table below.

When there are no keel files：

Detection item	Judgment	Routing Suggestion
Existing Scaffold + New Requirement Intent	docs/prd/requirements/index.md already exists, and the user describesa new requirement different from the current one(must be determined before the PRD candidate row below, otherwise unreachable)	Route /prd, via itsNew Requirement Gate⚠️Choose one of three (continue current / create new after clear / create new after discard); if unconfirmed ⛔ do not overwrite
PRD Candidate (Continue Current Requirement)	Detect docs/prd/requirements/index.md(single-requirement scaffold, flat unique path), and the user intent is to continue/consume the current requirement; if present, read maturity; if absent, skip	If present, read maturity; if 0, skip
maturity=ready	Product Requirement Ready (Continue Current Requirement)	Suggest /requirements --from-prd docs/prd/requirements/index.md
maturity=idea/draft	Product Requirement Package Not Ready (Continue Current Requirement)	Suggest /prd continue refining the requirement
Has src/、lib/、app/ and other code	Q1a: New project or existing project	Existing project → /retrofit; scaffold/template → continue routing by input type
User input is extremely short (<200 characters, unstructured)	Vague idea	Suggest /prd explore the requirement
File/URL/Long text	Large document reference	Suggest /prd prd parse the document

When keel files already exist：

Detection Item	Routing Suggestion
Has 00-baseline.md and no 01~04(baseline established, no requirement yet)	New requirement → /feature; supplement background → /requirements --context
verify-report（--impl / all, passed)	/sync or /compound
Code commits + tasks in progress	Continue /dev-workflow
Has 01–04 + readiness-report passed	/dev-workflow
Has 01–04 + readiness not passed or missing	/verify --readiness
Has 01–03	/dev-tasks
Has 01 + 02	/test-cases
Only 01-requirements.md	/system-design
05-insights.md contains ⏳ pending-confirmation items	/insights after confirmation, proceed to system-design or dev-tasks

⛔ "Baseline State" must be placed first in the table. Baseline project docs/devdocs/ existence will enter this table, but except for this rowmatches no row—the shortest row in the original table is "Only 01-requirements.md", and baseline projects will fall through directly.

Report-type files (readiness-report, verify-report) should be newer than their source files; when outdated, suggest re-verification.

ℹ️ Suggestion: AGENTS.md is missing the "Workflow Routing" section (existing keel project) → suggest /agent-memory --update to complete it; does not block routing. ℹ️ Suggestion: detected that 01 (or 01+02) has been produced → you may /board generate a visual review page (human review of requirements/design; non-blocking, not mandatory).

One-time upgrade prompt (after phase detection)

After phase detection is complete and before returning the routing suggestion, perform a lightweight drift check.The two categories are semantically different; do not mix them up(maintainer note: health never hooks back into ack):

A. Upgrade-type drift (one-time version decision, controlled by .devdocs-realign-ack )

schema drift(Artifact template): Detect each artifact spec_version difference from each skill's current constants → prompt /pipeline realign

When drift is detected and there is no .devdocs-realign-ack marker, printone-timelightweight prompt (does not block the original routing). For rules see references/realign.md § One-time upgrade prompt.

B. Health-type drift (continuous monitoring signal, baseline-aware,notcontrolled by .devdocs-realign-ack / --no-realign )

1. health drift(documentation health): run a cheap probe during routing (≤2s, only stat .claude/rules/devdocs-state.md size + the single-line length of that file,nofull scan,notouching frontmatter/dead links/ADR) → if hit, a one-line non-blocking prompt /pipeline realign --scope=health(run a full scan).

Semantic fork (critical, do not degrade): the upgrade type is "version lagging → upgrade decision", and permanent silence after ack is reasonable; the health type is a monitoring signal of "continuous documentation degradation",never attach ack— otherwise even if the state file grows to 209KiB, it will only remind once and then be permanently muted. health re-evaluates by .health-baseline.yml each time it enters routing: acknowledge existing debt and only report newly added degradation. For probe signals, baseline comparison, and in-session deduplication see references/realign.md § health drift probe.

.devdocs-realign-ack Read/write responsibility: reading occurs after stage detection;writing is triggered only when pipeline realign / --no-realign completes execution(whole-repository decision) — feature F-XX realign / bugfix BUG-XX realign is targeted local alignment,does not write ack(the user has not made a decision for the whole repository; the next time it enters the pipeline, if drift still exists it should still prompt; if the targeted realign happens to clear all drift, then the pipeline entry naturally has drift_count=0 and will not prompt). For invalidation conditions see references/realign.md. The marker file is committed to git, and collaborators share the decision.

Adaptive Harness Depth

Automatically recommend process depth based on the impact scope of the change, avoiding lightweight tasks being dragged down by heavy processes, while ensuring high-risk changes do not miss verification.

Tier	Characteristics	Process depth	Routing
Lite	Single-file change, no new interfaces, configuration change, UI fine-tuning	requirements(incremental) → dev-tasks → dev-workflow	/feature "<描述>"(indicating it is a small change) or /pipeline bugfix
Standard	Multi-file changes, new interfaces, new modules	full process (requirements → design → tests → tasks → dev)	/pipeline feature
Deep	Cross-module architecture changes, security-related, core data model changes	full process + mandatory independent review + mandatory documentation alignment verification	/pipeline feature(indicating it is an architecture-level change)

Automatic detection signals：

Signal	Detection method	Recommended tier
Files involved ≤2 and no new interfaces	User description analysis	Lite
New API/data model/module	User description + comparison with existing 02-system-design	Standard
Cross-module dependency changes / security-related / core table schema changes	User description + architecture summary	Deep

Principles:Minimum viable Harness（Reference) — Each process step is an assumption encoding of model limitations, and as model capabilities improve, whether they are still necessary should be periodically evaluated.

Fallback Q&A

When stage detection cannot determine, converge through 2-3 questions:

Q1: "项目已有 keel 文档吗？"
    │
    ├── 没有 → Q1a: "已有代码还是全新项目？"
    │           ├── 全新项目 → init
    │           └── 已有代码 → /retrofit（非 pipeline 管辖）
    │
    └── 有 → Q2: "你要做什么？"
              ├── 新功能  → feature
              ├── 修 Bug  → bugfix
              ├── 检查质量 → verify
              ├── 吸收外部参考 → insights
              └── 收尾/沉淀 → close

Q3（feature/bugfix 追加，可选）:
    "这次改动涉及 UI 吗？"
    ├── 是 → verify 阶段包含 --ui 维度
    └── 否 → verify 阶段仅 --docs/--impl

Entry Point Details

Entry Point	Applicable Boundaries	Call Order / Routing	Required Summary Fields
init	Brand-new project, complete process from requirements to development⚠️ dev-workflow returns partial(milestone pending verification), stop at this step	Publish status inquiry(see note below) → requirements → agent-memory --update(governance delegation, see note below) → system-design → test-cases → dev-tasks → verify --readiness → dev-workflow(batch) → verify --docs --impl → sync	output_files、new_ids.features、new_ids.acceptance, each stage's status
feature	Existing project adding new features; automatically select Lite/Standard/Deep by Harness⚠️ dev-workflow returns partial , stop at this step	feature(built-in requirements/design/tests/tasks + Step 4.5 readiness + Step 6 dev-workflow) → verify --docs --impl → sync	entry, Harness tier, impact scope summary,output_files、new_ids
bugfix	Fix bugs; does not change feature entry semantics	Simple bug:bugfix → verify --impl → sync; complex bug:dev-tasks → dev-workflow → verify --impl → sync	Bug scope, complexity determination, fix files, verification results
verify	Quality check at any stage	Code changes → verify --impl; document changes → verify --docs; UI design mockups → verify --ui; uncertain → ask the user; then route to the corresponding skill to fix	Check dimensions, issue summary, recommended fix skill
close	Wrap-up at the end of the development cycle (requirement termination after launch)	sync（trace + audit）→ compound(knowledge deposition) → onboard --update → prd clear(clean up the current requirement scaffolding, execute as the final step to ensure the why memory has been deposited); when the health probe hits blocker level, secondary reinforcement: suggest also realign --scope=health full scan	Sync results, deposited files, updated context summary, scaffolding cleanup results
insights	External insight absorption⚠️ dev-workflow returns partial , stop at this step	insights(collection + user confirmation + append 01) → if there are architectural changes then system-design → test-cases → dev-tasks → verify --readiness → dev-workflow → verify → sync; for simple improvements then dev-tasks → dev-workflow → verify → sync	Insight confirmation results, architectural impact determination, change chain
design	User actively pushes design assets; pipeline only performs stage detection and collection	no-prd → collect and prompt to first /prd or /requirements；prd-ready → requirements --update-design --target prd-index；post-requirements/post-design → requirements --update-design; in-dev → requirements --update-design + prompt verify --ui; post-tasks → requirements --update-design → dev-tasks --backfill-design	design_context, target stage, delegation target, UI verification prompt
backlog	Deferred task pool maintenance (park / close / supersede / list / init)	Delegate backlog, pass in source_id and action	Entry status transition results, current in-pool list
realign	Rescan completed artifacts after specification upgrade; do not destroy original completion evidence, only append gap remediation	Scan frontmatter → compare each skill's current constants → Phase 1 B-class upstream → Phase 2 A-class main chain → Phase 3 B-class bypass → summarize yaml-summary-v1	Number of drifts, Phase results, confirmation items

Entry Point Private Constraints

• Governance delegation (init chain agent-memory --update):requirements completed (first produced docs/devdocs/) then immediately Task: /agent-memory --update, ensuring the workflow routing section is persisted as early as possible (interruptions are also shipped).Result branch adaptation: this is an optional governance step, and the general "failed+blockers → user decides" branch does not apply —success normal record;partial/failed/interrupted retain the original status and blockers, display ℹ️, thencontinue the main chain. Narrow write-scope exception: only agent-memory is allowed to write its managed memory file (AGENTS.md/CLAUDE.md imported lines/.claude/rules/devdocs-state.md), all other business files remain prohibited.
• readiness gate：dev-tasks must be called afterward verify --readiness; check AC↔test case alignment, task file path specificity, dependency acyclicity, design↔task consistency. If P1 is blocked, show the issue list, then retry after fixing.
• Full supplementary verification：dev-workflow batch mode already includes per-task sync + compound internally; the pipeline's post-stage verify → sync is full verification + idempotent supplementary sync, and no additional compound is executed.
• Context passing: at startup, docs/devdocs/00-context.md can be read as reference, but stage detection always uses the actual docs/devdocs/ files as the standard.
• Deep mode: for cross-module / architecture / security changes, all dev-workflow tasks are forced to --review, and after feature completion, verify --docsis additionally executed, with an impact summary shown.
• Sprint Contract coordination：test-cases takes the produced executable acceptance contract as dev-workflow input; the pipeline passes only the summary, file paths, and new numbers, without inlining the full test text.
• design proactive push: for detailed protocol see ../prd/references/design-context.md; the pipeline does not write documents, no-prd does not block, and it does not interrupt the current dev-workflow.
• Release status question (init first step, source-level governance)：init at the start, AskUserQuestion asks once"Has this project been released?". Not released → ⛔ do not apply semver; express progress with Sprint / stage code / backlog pool (⛔ do not write "milestone" here —M-XXX is the requirement segmentation concept in 01 §2.5, and the same name would be misread); released → semver is a real contract, use it normally. The conclusion is written by agent-memory --update into the "Conventions" section of AGENTS.md, and subsequent skills use it to decide how to express progress.
  • Ask only this one question, ⛔ do not follow up on which convention specifically to use — that can be decided later as needed, and interrupting once more at kickoff is not worth it.
  • Reason: version numbers and progress area self-created current state, cannot be read from the code, and naturally need someone to define them. When there is no real release node to rely on, version numbers can only be used as placeholders, and once heavily referenced, regression is hard to prevent; asking once at the source costs far less than cleaning up afterward.
  • For taking over an existing project, follow retrofit, the same question is asked in 00-baseline.md §2.1, and the conclusions of both paths are recorded in AGENTS.md.
• close scaffolding cleanup: the last step of close delegates to prd clear to clean up the docs/prd/ one-time scaffolding; first dry-run the scope + impact (orphans / unsynced items are not deleted by default), ⚠️ deletion with --apply must be confirmed; when there is no docs/prd/ , silently skip. The pipeline only delegates and does not delete files itself (see prd Clean up scaffolding）。
• realign coordination mechanism: realign is a non-continuation signal; restructuring gaps must ⚠️ 必须确认; additive can be directly filled in; second run is idempotent;--headless must be explicit --realign or --no-realign。
• Workspace topology (init）：requirements after completion (first time producing docs/devdocs/) execute Task: /workspace-topology reconcile. This skill writes its own AGENTS.md the workspace: block,without agent-memory ghostwriting——devdocs_frontmatter the input parameters no longer pass the workspace field. When there is no declaration, it asks once for the mode and code root and records the declaration, after which it no longer asks. Also at the beginning of the process call /workspace-topology inspectonce, and pass the result down through the handshake's workspace_context to each atomic skill (see shared/constraints.md §3 task/workspace-context). The retrofit scenario's path is carried by retrofit/SKILL.md itself.

Sprint Contract handshake

When the pipeline starts test-cases and dev-workflow , retain the minimal context for cross-skill collaboration:

Source	Destination	Required content	Rules
test-cases	dev-tasks	UT/IT/E2E numbering, covered ACs, test file suggestions	Pass only a summary + file paths; downstream reads the specific test design itself
dev-tasks	verify --readiness	Task list, dependencies, task ↔ AC/test mapping	Block entry into dev-workflow when readiness fails
verify --readiness	dev-workflow	Pass status, evidence of zero P1 blockers, executable task scope	Development execution must not start without passing evidence
dev-workflow	sync / verify	Completed tasks, modified files, test results, trace changes	Full post-pipeline verification, covering omissions across tasks

realign / layout coordination details

realign handles the spec_version dimension, and the pipeline aggregates yaml-summary-v1.

Dimension	Scan source	Scheduling / migration phase	Output
spec_version	frontmatter of each artifact + each skill references/realign.md current constant	Phase 1 Category B upstream → Phase 2 Category A main path → Phase 3 Category B bypass	drift list, per-skill summary, remaining blockers

Inter-phase handoff

After each phase is completed, the pipeline:

1. Status check: confirm that the phase output file exists
2. Brief summary: show the user an overview of this phase's results
3. Handoff prompt: ask the user whether to continue to the next phase (default yes)

✅ 需求文档已完成（F-001~F-003, AC-001~AC-012）
是否继续进入系统设计阶段？[是(默认)/否]

Orchestration specification (sub-agent scheduling)

Scheduling principles

When the pipeline calls other skills,it must launch a sub-agent through the Task tool：

pipeline（编排层）
    │
    ├── Task: /requirements → YAML 摘要
    ├── Task: /system-design → YAML 摘要
    ├── Task: /test-cases → YAML 摘要
    ├── Task: /dev-tasks → YAML 摘要
    ├── Task: /verify --readiness → YAML 摘要
    ├── Task: /dev-workflow → YAML 摘要
    ├── Task: /verify → YAML 摘要
    └── Task: /sync → YAML 摘要

Summary passing

Only the YAML summary + file paths are passed between phases. The orchestration agent does not readthe sub-skill's complete output document.

Exception fallback

When a sub-agent returns status: failed + blockers :

1. Show the blocker to the user
2. Ask the user how to handle it (fix/skip/terminate)
3. Do not read documents on your own to troubleshoot

Sub-agent returns status: partial when (⛔ must not be treated as complete):

1. Show blockers and summary.details pending confirmation items
2. ⛔ Stop here, do not proceed to the next stage of the chain
3. Provide a continuation entry point (next_recommended), the user decides when to continue

dev-workflow 's milestone segment endis the most common source of this branch: a segment of implementation is complete, awaiting user validation through actual use. It is not a failure, but itmust neverbe treated as the development stage being complete and continue running verify → sync — that would amount to bypassing the user validation gate, which is precisely the reason this mechanism exists. The criterion only looks at the envelope:status: partial + details.milestones_pending is non-empty. ⛔ pipeline does not read output documents, does not read checkpoint files.

Context isolation

Each sub-Agent reads the prerequisite documents it needs on its own (from the docs/devdocs/ filesystem), without relying on the orchestrating Agent to pass the full text.

Constraints

keel 6-stage governance

From the pipeline perspective, the main chain stages are fixed as:

1. requirements: encode structured requirements and AC
2. system-design: complete the technical design and interface boundaries
3. test-cases: produce UT/IT/E2E and Sprint Contract
4. dev-tasks: break down executable tasks and dependencies
5. dev-workflow: execute development per task and verify task by task
6. verify/sync: full verification, traceability sync, and wrap-up

insights, design, and realign are entry or governance branches and do not change the order of the 6-stage main chain; bugfix can take an independent fast path or fall back to dev-tasks → dev-workflow.

Stage boundary constraints (global rules)

The keel workflow strictly distinguishes thedocument stageand thecoding stage：

Stage	Skill	Output type	Coding allowed
Requirements	requirements	Document	❌
Design	system-design	Document	❌
Test design	test-cases	Document	❌
Task breakdown	dev-tasks	Document	❌
Project retrofit	retrofit	Document	❌
Development execution	dev-workflow	Code	✅
Bug fix	bugfix	Code	✅

• ⛔ Do not continue: the document stage must not produce implementation code, only write docs/devdocs/ Markdown documents under(recovery method: move the code output to the dev-workflow/bugfix stage)

Orchestration constraints

• pipeline is only responsible for routing and linking, and does not duplicate the logic of any atomic skill
• Each stage must be delegated to the corresponding atomic skill for execution
• The information passed between stages is limited to: newly added numbered lists, status summaries, file paths

Question-based scheduling constraints

• Prefer using stage detection for automatic determination, and only ask questions when determination is impossible
• Fallback Q&A converges to the entry point with at most 3 questions
• Questions must have clear options (no open-ended questions)
• When a retrofit scenario is identified, route to /retrofit and exit pipeline
• The track-splitting hint is based on change scale and does not introduce additional terminology

Context constraints

• Read 00-context.md first as quick context (if it exists and is < 24h old)
• The pipeline orchestration layer does not read large amounts of source code (delegates to sub-skills)
• After each phase completes, display a brief summary (< 10 lines)

Orchestration Constraints (Sub-Agent)

• When invoking other skills, a sub-Agent must be launched via the Task tool
• When a sub-Agent fails, display the blocker and ask the user; do not troubleshoot on your own
• Each sub-Agent reads the prerequisite documents itself; the orchestration layer does not pass full text

Skill Collaboration

Entry	Orchestrated Skill Chain
init	requirements → system-design → test-cases → dev-tasks → verify --readiness → dev-workflow → verify → sync
feature	feature (including readiness + dev-workflow) → verify → sync (in the Deep tier, dev-workflow enforces independent review + verify includes --docs)
bugfix	bugfix / (dev-tasks → dev-workflow) → verify → sync
verify	verify --docs/--impl/--ui
insights	See the insights flowchart below
close	sync → compound → onboard --update → prd clear (scaffolding cleanup, dry-run→⚠️confirm→delete)
design	Phase detection → delegate to requirements --update-design [→ dev-tasks --backfill-design]
realign	Phase 1 Category B upstream: prd-parser/prd-brainstorm --realign (if present) → Phase 2 Category A main chain: requirements → system-design → test-cases → dev-tasks → dev-workflow --all → Phase 3 Category B bypass: insights/onboard (if present) (see references/realign.md）

Additional Notes: In batch mode, dev-workflow internally invokes /test-run --trace to run the full test suite + traceability verification; see skills/dev-workflow/SKILL.md。

insights Entry Flow

/insights（收集 + 用户确认 + 追加 01-requirements.md）
    │
    ▼
评估是否涉及架构变更
    │
    ├── 有架构变更（新 API / 数据模型 / 新模块）
    │   └── /system-design → /test-cases → /dev-tasks
    │       → **verify --readiness** → /dev-workflow → /verify → /sync
    │
    └── 简单改进（纯配置 / 样式调整）
        └── /dev-tasks → /dev-workflow → /verify → /sync

Sub-Agent Summary Format

When this Skill runs as a sub-Agent, return yaml-summary-v1; for the full envelope see ../shared/constraints.md § 2. pipeline private fields go only in summary.details：

summary:
  headline: "init 流程完成 2/5 阶段"
  details:
    entry: init | feature | bugfix | verify | close | insights | design
    harness_depth: Lite | Standard | Deep
    stages_completed:
      - { skill: requirements, status: success }
      - { skill: system-design, status: success }
    stages_remaining:
      - test-cases
    interrupt_reason: "用户选择退出"  # 仅中断时

Field	Meaning
entry	This entry point must correspond to one of the run modes
harness_depth	Lite, Standard, Deep determination for feature / bugfix scenarios
stages_completed	Completed phases and sub-Agent status
stages_remaining	Remaining phases when the user interrupts or it is partial
interrupt_reason	Record the user's choice or environment limitations only on interruption

output_files、new_ids、next_recommended still uses the shared envelope fields; pipeline only fills in file paths, newly added numbers, and the next suggested skill, without extending field semantics.

Next Steps

After pipeline completes, all output documents have been generated/updated. The user can:

• Continue with the next round of feature/bugfix
• Run /onboard --read to pass context to a new AI

⚠️ When developing a new feature, you must not skip test-cases, dev-tasks, or verify --readiness and go directly into dev-workflow. Bug fixes follow the /pipeline bugfix path.