PRD: cc-devflow skill content architecture contracts

[Dimon94]

Problem Statement

cc-devflow 的 skill 内容链路已经形成了完整工作流，但多个关键合同仍散落在各个 skill、playbook、reference、template 和测试里。当前最大问题不是分发框架，而是 skill 开发内容框架本身：核心 Agent 链路需要靠重复 prose 记住 task.md、阶段路由、质量门、并发环境、skill 写作标准和测试证明面。

从用户视角看，这会带来三个问题：

1. Agent 运行时容易依赖聊天记忆或局部文案，而不是读取一个稳定合同。
2. 修改一个 skill 时，很难知道哪些下游 skill 也需要同步。
3. 现有测试偏向文案断言，能防删句子，但不够证明链路过程可预测。

用户希望把架构报告中的 6 个优化点合并为一个总 PRD，再拆成 6 个可并行开发的 issue。目标是让 cc-devflow 的底层 skill 链路变成一组小而深的 Chain Skill，每个合同有明确边界，被 User Entry Skill 和 Agent-facing workflow skill 复用。

Solution

新增和收敛 5 个 Chain Skill / contract surface，并补一组 workflow fixture tests：

1. skill-authoring-gate：定义写 skill 的质量门。
2. task-contract：定义 task.md durable contract。
3. workflow-chain-contract：定义阶段状态机、reroute 和 terminal states。
4. quality-gate-contract：定义 review/check/simplify/act 之间的质量门语义。
5. execution-environment-contract：定义并发环境图、child dispatch 和集成合同。
6. workflow fixture tests：用最小 Jest fixtures 测过程可预测性，而不是只测文案存在。

这些不是 6 个独立大项目，而是一组分层合同。skill-authoring-gate 是写作标准，其他合同用它做尺；task-contract 和 workflow-chain-contract 是后续并发和测试的基础；quality-gate-contract 与它们并行收敛质量语义；execution-environment-contract 依赖 task 和 workflow；fixture tests 最后把过程证明面补上。

User Stories

1. As a cc-devflow maintainer, I want shared workflow concepts to live in Chain Skills, so that individual skills do not duplicate core contract prose.
2. As a skill author, I want a Skill Authoring Gate, so that every skill change can be checked for invocation, information hierarchy, completion criteria, progressive disclosure, leading words, and pruning.
3. As a human user, I want User Entry Skills to stay distinct from Chain Skills, so that I do not need to remember internal workflow contracts.
4. As an orchestration agent, I want Chain Skills to be Agent-facing contracts, so that I can load stable rules without depending on chat memory.
5. As a planning agent, I want a Task Contract, so that task.md shape and semantics are defined in one place.
6. As an execution agent, I want task block fields and completion semantics to be stable, so that I can select and complete tasks without reinterpreting prose.
7. As a verification agent, I want Failure Ledger and evidence semantics to be stable, so that pass/fail/blocked decisions are honest.
8. As a review agent, I want findings and review escapes to share one quality contract, so that review output routes consistently.
9. As a simplification agent, I want confirmed smell semantics to be part of the quality gate, so that cc-simplify is not an isolated late-stage rule set.
10. As a closeout agent, I want postmortem and delivery inputs to use the same quality gate language, so that cc-act does not reinterpret raw failures.
11. As a workflow orchestrator, I want a Workflow Chain Contract, so that phase transitions, reroutes, and terminal states have one source of truth.
12. As a parallel execution orchestrator, I want an Execution Environment Contract, so that child dispatch, dependency gates, integration, and closeout are defined outside platform-specific tooling.
13. As a Codex App operator, I want platform-specific thread tools to remain outside the Execution Environment Contract, so that the contract is not tied to one host implementation.
14. As a package maintainer, I want internal Chain Skills to be distributed when core skills read them, so that installed skill packs remain complete.
15. As a package maintainer, I want Chain Skills not to become public entry skills by accident, so that distribution does not increase human cognitive load.
16. As a release reviewer, I want retired CLI/process artifacts to remain blocked, so that new Chain Skills do not revive old machine artifact flows.
17. As a test maintainer, I want workflow fixture tests, so that process behavior is verified through small stable seams.
18. As a test maintainer, I want to avoid broad snapshots, so that contract wording can improve without breaking low-value tests.
19. As an implementer, I want six separately grabbable issues, so that multiple agents can work in parallel without editing the same contract surface.
20. As a future maintainer, I want dependency relationships between issues to be explicit, so that parallel work does not create semantic conflicts.

Implementation Decisions

• Define User Entry Skill as a skill a person invokes to start or resume a workflow phase.
• Define Chain Skill as a skill used by other skills and agents inside the workflow chain, not as a primary human entry point.
• Define Task Contract as the durable agreement that defines the shape and meaning of task.md for planning, execution, verification, and delivery.
• Implement skill-authoring-gate as a Chain Skill, not as a loose checklist.
• skill-authoring-gate covers invocation, information hierarchy, completion criterion, progressive disclosure, leading words, and pruning.
• Implement task-contract as a pure reference Chain Skill.
• task-contract covers task.md sections, status enum, task block fields, Failure Ledger semantics, Execution Environments semantics, and reader/writer responsibilities.
• task-contract does not own workflow routing, review convergence, delivery choice, parser/DSL/validator behavior, or CLI commands.
• Implement workflow-chain-contract as a Chain Skill for phase state machine semantics only.
• workflow-chain-contract covers main route, bug route, PR route, terminal states, reroute semantics, and entry/exit evidence per phase.
• workflow-chain-contract does not duplicate task.md structure, quality finding semantics, child worktree dispatch, or skill-writing rules.
• Implement quality-gate-contract as a Chain Skill covering quality gate semantics across review, verification, simplification, and closeout.
• quality-gate-contract includes cc-simplify only at the confirmed-smell / gate level, not its full internal reviewer swarm workflow.
• Implement execution-environment-contract as a Chain Skill covering parallel graph and integration semantics.
• execution-environment-contract covers E/R/C/A/EF environment types, dependency fields, child dispatch boundary shape, child final report, integration gate, and worktree closeout.
• execution-environment-contract does not wrap Codex thread tools, heartbeat implementation, model selection, or platform UI behavior.
• Add workflow fixture tests inside the existing Jest suite. Do not introduce a new test framework.
• Keep generated skill mirrors generated. Do not hand-edit mirror output as source truth.
• Keep issue scope separated so early contracts can merge before dependent contracts and fixtures.

Testing Decisions

• Highest useful seam for distribution and retired-guard behavior is publish validation.
• Highest useful seam for Chain Skill wiring is source skill metadata and reads relationships.
• Highest useful seam for process behavior is small workflow fixtures in Jest.
• Avoid full-file snapshots and exact long prose checks.
• Use real repository files, config, and scripts instead of mocks where practical.
• Include at least these fixture categories:
  • serial workflow fixture: task contract handoff through execution selection, verification verdict shape, and closeout input
  • parallel fixture: Execution Environments, child dispatch boundary, and integration gate fields
  • quality fixture: review finding, Failure Ledger candidate, check classification, and act/postmortem trigger input
  • authoring fixture: frontmatter, reads wiring, no user trigger for Chain Skills, and completion criteria presence where applicable
• Do not use real child threads, real GitHub PRs, or external services in fixture tests.
• npm run adapt:codex remains the proof that source skills can generate Codex mirrors.
• npm run verify:publish remains the release-facing proof that the package surface is coherent.

Out of Scope

• No new parser, DSL, schema compiler, or full validator for task.md.
• No new CLI command for these contracts.
• No revival of retired task manifest, change metadata, review ledger, or report-card artifacts.
• No platform-specific Codex thread abstraction inside the contract skills.
• No real child-thread orchestration in tests.
• No redesign of GitHub PR landing or remote review workflows.
• No broad documentation rewrite unless a contract explicitly requires a small reference update.
• No attempt to make all six issues fully independent; dependencies are part of the design.

Child Issues

• Add skill-authoring-gate Chain Skill #41 Add skill-authoring-gate Chain Skill
• Add task-contract Chain Skill #42 Add task-contract Chain Skill
• Add workflow-chain-contract Chain Skill #43 Add workflow-chain-contract Chain Skill
• Add quality-gate-contract Chain Skill #44 Add quality-gate-contract Chain Skill
• Add execution-environment-contract Chain Skill #45 Add execution-environment-contract Chain Skill
• Add workflow fixture tests for skill contracts #46 Add workflow fixture tests for skill contracts

Dependency Plan

• Add skill-authoring-gate Chain Skill #41 can start immediately.
• Add task-contract Chain Skill #42 is blocked by Add skill-authoring-gate Chain Skill #41.
• Add workflow-chain-contract Chain Skill #43 is blocked by Add skill-authoring-gate Chain Skill #41.
• Add quality-gate-contract Chain Skill #44 is blocked by Add skill-authoring-gate Chain Skill #41.
• Add execution-environment-contract Chain Skill #45 is blocked by Add task-contract Chain Skill #42 and Add workflow-chain-contract Chain Skill #43.
• Add workflow fixture tests for skill contracts #46 is blocked by Add task-contract Chain Skill #42, Add workflow-chain-contract Chain Skill #43, Add quality-gate-contract Chain Skill #44, and Add execution-environment-contract Chain Skill #45.

Parallel strategy: run #41 first or alongside drafting work; then run #42, #43, and #44 in parallel after #41 is available; then run #45 and #46 after their contract dependencies are merged.

Further Notes

This PRD intentionally keeps all six architecture improvements under one product umbrella, while preserving issue boundaries for parallel execution. The contracts should stay boring and narrow. If a contract starts absorbing another contract's responsibility, split that content back out instead of widening the current Chain Skill.