cs-epic

cs-epic

Converge a large requirement from route fog into an executable contract, then complete deliverable sub-items one by one, keeping the full picture always visible to the user.

Start work

• If there is .codestable/attention.md , read it first.
• By task keywords, grep in the existing .codestable/lessons/, project docs, and the v1 read-only knowledge directory .codestable/roadmap/、.codestable/features/、.codestable/issues/、.codestable/refactors/、.codestable/goals/、.codestable/compound/、.codestable/audits/、.codestable/brainstorms/、.codestable/feedback/ ; report the source path of any hits. The above v1 directory is read-only; do not continue generating, rewriting in place, or batch-migrating within it; graduate new conclusions into permanent Epics, project docs, ADRs, or lessons.
• .codestable/requirements/ Maintain .codestable/attention.md explicitly records it as the canonical requirement location; when the owner designates it for the first time, first write that project fact into attention. When not recorded, treat as read-only; when it does not exist, do not create a new .codestable/requirements/; new projects follow the project's own documentation structure, and stable contracts whose destination is undetermined stay in the permanent Epic for now.
• When there is a matching .codestable/work/epic-{slug}.md , resume first: read its permanent Epic pointer,phase、 approved_revision、item_progression、milestone_commit and remote_publish, and verify the current SHA-256 of the active permanent document. When the cursor does not hit, first scan by task keywords within the project's existing clear Epic, RFC, or initiative destinations for in-flight Epics in status: proposed ; when .codestable/epics/ exists, also scan candidates within it under the same conditions. When both types of destinations coexist, include both as candidates, with the project's existing destination taking priority. On a unique hit, only restore the missing planning cursor and resume. On multiple hits, disambiguate by slug, task keywords, and permanent document pointer; if still not uniquely determined, list the candidates and ask the owner to choose; do not auto-merge, fill in the cursor, or create a new Epic. Repository facts take precedence over chat history; when hashes, policy fields, or repository facts are inconsistent, fix them first or request context; do not create duplicate Epics.
• When drafting the proposed permanent Epic document, simultaneously create or reuse the corresponding work cursor and keep phase: planning、approved_revision: pending、current_item: null。
• When the same session is handed in by cs with a confirmed handoff, directly consume the target entry, original request, goal or expected behavior, scope/non-goals, acceptance, verified repository facts and their sources, owner-confirmed terminology and decisions, open risks, canonical asset pointers or asset candidates; do not re-ask about matters already confirmed within the packet's exact scope. A handoff only proves consensus for the current session; it does not expand authorization to implement, commit, release, or write, nor does it replace this skill's review, verification, and confirmation gates; reconfirm per this skill's rules when fields are missing, repository facts conflict, a new risk that would change the outcome appears, a fact that would change direction is missing, or the confirmed boundary is exceeded.
• A handoff is only used to draft the proposed permanent Epic document; it does not replace fresh design review, the approved hash, or the first owner gate.
• Clarify the requirement: ask only questions that would change the decomposition direction (goal boundaries, priorities, acceptance criteria), at most 3 at a time, and stop once consensus is reached.
• When new terms, overloaded terms, or adjacent concept boundaries would change the goal, scope, factual authority, lifecycle, acceptance, or sub-item contract, read references/shared-language.md; even if full route discovery is not triggered, the determinable Language Clear conditions within it must still be met. Do not add sections or questions for existing unambiguous terms.
• After completing the bounded repository investigation and at most 3 current directional clarifications, if a reviewable proposed Epic still cannot be written due to multiple interdependent route-level decisions, and convergence within the current session is not expected, read only when the route is still unclear references/wayfinding.md. The route is already clear, only a single local technical unknown remains, or it is skipped solely because of high risk, many files, or cross-session work.

Continuous learning

After retrieving a lesson, first do read-repair. Perform only one bounded, lowest-cost targeted verification, preferring to read existing code, tests, or canonical documentation; do not run large-scale tests or repeatedly reproduce merely to verify a lesson. If still insufficient, skip that lesson and do not block the normal task. Only entries whose scope matches, are not retired, hold under current facts, and genuinely change the plan or verification, or explicitly rule out a specific and reasonable wrong path, count as valid hits; report by 经验命中：{path}（{status}）；核验：{fact}；影响：{plan_or_check} report.retired do not apply; observed / validated verify first, then use; old lessons lacking status read by observed , do not batch migrate. When merely relevant but not behavior-changing, do not manufacture reuse evidence; when current facts clearly refute it, stop applying immediately; when evidence is insufficient, do not guess.

Within a task, keep at most 3 candidates in memory, replace low-value items based on new evidence, and do not pause or ask. Strong signals include only: the owner corrects something and actually changes the plan/code/terminology/verification; reproducible evidence overturns the root cause; after the same path fails twice, the hypothesis is changed; a blocking/important finding exposes an unencoded invariant; a new red -> green captures a reproducible failure; a lesson genuinely changes this behavior or is refuted; a workaround repeats; a method significantly reduces retries, cost, or risk.

A candidate must also simultaneously have traceable evidence, be expressible as a future action, apply beyond this exact diff, and have no existing canonical owner. Network fluctuations, spelling, generic slogans, activity records, and facts already fully covered by a mechanical owner are discarded directly.

Creating and rewriting rules/scope, promotion, deletion, and cross-project feedback still require explicit user authorization. To avoid interrupting read-repair, only two narrow maintenance operations are open for lessons that already exist and are valid hits:observed -> validated occurs only when an independent subsequent task actually adopts it and verifies it successfully, adding only one representative piece of evidence; it must record the plan or verification that the lesson actually changed, or the specific and reasonable wrong path it explicitly ruled out, as well as the acceptance evidence passed this time.observed|validated -> retired occurs only when current repository facts directly refute it or an existing canonical owner is found, writing only the reason and the replacement/refutation pointer. Narrow maintenance does not create new facts, change rules, expand scope, or add new gates, and enters the same semantic atomic milestone along with the current code, evidence, and cursor; stable validated hits do not write files. When the conclusion needs rewriting or evidence is insufficient, only provide candidates; new conclusions must not obtain validated identity by reviving retired entries; narrow maintenance must list file changes in the final report.

Constraints within the current task scope that can be directly turned into a red -> green test/checker are prioritized for mechanization, without writing a separate duplicate lesson; when it would expand the scope, only provide candidates. When the user has explicitly said "remember / update / retire", handle it in the same round by cs-keep , without repeated confirmation. Epic subitems are not displayed and not asked about; each subitem writes at most one deduplicated candidate into the existing cursor evidence area, using the 晶化候选：{rule} marker, and the final graduation list is processed once and reuses the final owner gate.

Two-layer Epic document

Epics are naturally cross-session, but stable context and activity status must not be mixed:

• Permanent Epic document: follow it if the project already has a clear Epic, RFC, or initiative home; otherwise create it as needed on first creation .codestable/epics/{slug}.md，cs-onboard Do not pre-create this directory. The permanent Epic document is the only route document; the proposed stage is the low-resolution in-document route map; it is the sole owner of the starting point, goals, scope, non-goals, acceptance criteria, conditional shared language and conceptual boundaries, sub-item contracts with stable IDs/dependencies/acceptance points, key decisions, final delivery index, overall acceptance, residual risks, and long-term status . During route discovery, also temporarily store the dependency-bearing 待决策 and 尚未明确, without adding separate issues, maps, or a third state system.
• execution cursor：.codestable/work/epic-{slug}.md stores only the permanent document pointer,approved_revision, execution phase, current sub-item ID, progress for each ID, next step,blocked_by、item_progression、milestone_commit、remote_publish, active_items recovery records under the parallel strategy, temporary decisions, and evidence/commit pointers; it must not copy goals, acceptance criteria, sub-item definitions, or final conclusions.

Minimum structure of the permanent document:

Sections with conditional annotations are created according to the conditions; when not triggered, the entire section is not written.

---
status: proposed
created: YYYY-MM-DD
work: ../work/epic-{slug}.md
---
# {epic 名}
起点 / 目标 / 范围 / 非目标 / 验收标准
## 共享语言与概念边界
<!-- 仅在术语歧义会改变路线时创建；链接已有 canonical 定义，只补本 Epic 的局部边界与关系 -->
## 关键决策
- **DEC-1 · {可读名称}**：{结论与理由；证据或资产指针}
## 待决策
- **DEC-2 · {可读名称}** `[AFK|HITL]`
  - question: {一个现在能精确陈述、且会改变路线的问题}
  - depends_on: [{完整决策名称} | none]
  - method: research | owner-dialogue | prototype | prerequisite
  - evidence: {pointer | pending}
<!-- 仅在触发路线发现时创建；route clear 冻结前移除本节 -->
## 尚未明确
<!-- 仅在触发路线发现时创建；暂时无法精确陈述的路线级迷雾不分配 DEC 名称或依赖；route clear 冻结前移除本节 -->
## 子项契约
- ITEM-1：{owning skill；可交付结果；依赖；验收要点；必要的设计约束}
## 最终交付索引
## 整体验收
## 遗留风险

Minimum structure of the work cursor:

---
epic: ../epics/{slug}.md
phase: planning
approved_revision: pending
current_item: null
next_action: {one concrete next action}
blocked_by: null
item_progression: pending
milestone_commit: pending
remote_publish: pending
---
## 子项进度
- [ ] ITEM-1
## 临时决策与证据

Permanent status only allows proposed -> active -> accepted; when the owner abandons it or replaces it with a successor Epic, it transitions to cancelled / superseded；work phase only allows planning -> executing -> acceptance; blocking only writes blocked_by。

Route discovery follows proposed + planning + approved_revision: pending, without adding states; before route clear, no unresolved HITL nodes may remain; nodes that are still valid must be explicitly resolved by the owner or confirmed to be moved into 非目标; only nodes that have mechanically become invalid due to confirmed upstream decisions may be deleted with justification; the agent must not unilaterally determine that they are out of scope or invalid. Terminology that would change the route must already be unambiguously defined, defined, or linked to a canonical owner, and sub-item contracts must use the same vocabulary; unresolved product meanings or conceptual boundaries are still handled as HITL. When the route is clear, reviewable, and executable, retire the 待决策 and 尚未明确 sections: write only the remaining AFK local unknowns into the corresponding sub-item contracts, and write only the residual risks from resolved decisions and delegated AFK local unknowns into 遗留风险, then freeze the complete proposed Epic and enter the existing design review. Route clear is not a new owner gate, nor does it mean that all local implementation details have been decided; for the judgment criteria, see references/wayfinding.md。

Breakdown confirmation itself does not equal version control authorization; the first owner gate simultaneously determines, in one go, item_progression: continuous | per-item | parallel、milestone_commit: authorized | manual and remote_publish: each-milestone | final | manual, explains that choosing manual commit will pause item by item, and writes it into the work cursor.parallel is provided only when the sub-item contracts contain sub-items whose dependencies do not block each other and that can be delivered in parallel;item_progression: parallel can only be paired with milestone_commit: authorized。milestone_commit: manual can only be paired with item_progression: per-item；milestone_commit: manual can only be paired with remote_publish: manual；remote_publish: each-milestone can only be paired with milestone_commit: authorized。authorized + per-item is a legal explicit item-by-item pause strategy. Before entering executing, pending or illegal combinations must not remain.

After the owner confirms the proposed document and the above strategy, the main process mechanically sets active, uses shasum -a 256 <epic-file> to compute the full file SHA-256, writes only approved_revision into work and enters executing; after approval, set current_item to the first sub-item whose dependencies are satisfied (in permanent document order);item_progression: parallel exception: after approval, initialize active_items: [] and keep current_item: null，current_item only during serial integration according to references/parallel-execution.md semantics. Before confirmation, keep pending and current_item: null. During active, the permanent document is frozen; daily progress and temporary decisions are written only to work; when goals, scope, non-goals, acceptance criteria, sub-item definitions, or major risks change, update the permanent document according to the same rules, re-review/confirm, and replace the hash. Version control policy changes update the cursor field only based on the owner's explicit expression, without modifying the permanent document or the approval hash, and authorization must not be inferred from historical operations. Existing commit authorization within an Epic refers only to milestone_commit: authorized; other values or session history alone do not count. If the old cursor is missing fields or has an invalid combination, pause once to supplement/correct the record.

Sub-item design prioritizes proximity: the brief design belongs to the sub-item contract in the permanent document; high-risk details may be recorded independently in work/feat-{slug}.md, with frontmatter marked epic: {epic-slug}, and the work cursor records only the path and progress. Adding or removing sub-items, or changes to dependencies or acceptance criteria, constitute contract changes; sequential fine-tuning that does not change dependencies/acceptance criteria only updates the cursor.

Hard gates

• The decomposition plan must be confirmed by the user(goals, boundaries, acceptance criteria, sub-item contract) before execution begins; while route-level fog remains, continue route discovery and do not submit for review prematurely. Once the route is clear, reviewable, and executable, enter the design review stage before submission for confirmation, and complete the following reviewer lineage cs-review. During execution after the permanent document has been approved, when goals, scope, non-goals, acceptance criteria, sub-item definitions, or major risks need to change, the contract change forms a new contract review stage: first update the permanent document, then have a fresh reviewer re-review it and obtain consent.
• Before the current main process creates a reviewer, first discover the subagent creation and management capabilities available in the current session. If the project context has explicit creation methods/model constraints, follow them first. After reaching the review quality baseline, prefer an agent heterogeneous to the implementer, and explicitly specify the strongest stable model; for the creation method, use in order the managed structured delegation capability, the host subagent, and the local bounded agent CLI fallback; do not merely scan PATH.
• When there is no qualified heterogeneous candidate, fall back to the strongest homogeneous model. Write the final creation method, agent/model, and fallback reason into the task packet; do not rely on the default model.
• Before review, freeze one explicit target (diff review prefers the staged diff, but an explicit range/patch may also be used; design review freezes the corresponding document version, and the legal forms are an existing design document version in the repository, or the verbatim full text + SHA-256 in the task packet; Epic design review prefers freezing the permanent document version; audit freezes commit + scope identifier), and write the target identifier into the task packet. In packet form, the first round gives the full text and hash verbatim to the reviewer, and the target the reviewer reviews is that text; finding-driven follow-up carries the latest full text, the before/after hashes, and a fix summary. Do not change the target or the corresponding working tree before the reviewer returns. When there are blocking issues or important issues not explicitly accepted by the user, do not submit the current candidate, and do not create a formal milestone commit; after handling, rerun verification and refreeze the complete review target.
• Only when cross-session recovery, agent handoff, or an isolated reviewer requires an immutable baseline, and commit authorization already exists, may a clearly marked WIP/checkpoint commit be created on a private working branch; it does not mean the review passed or the task is complete, and before delivery it must be fixed up/squashed according to repository policy.
• After this skill's confirmation and verification gates are all satisfied, blocking issues are cleared, and the remaining important issues have been handled or explicitly accepted by the user, create a semantically atomic formal milestone commit only when commit authorization already exists; if not authorized, only report the committable status and do not commit on your own.
• An independent review stage is defined by a single review purpose; design review, change review, contract review, and Epic final acceptance are different stages. Only the re-review of fixes made for this stage's findings belongs to the same stage and continues the original reviewer lineage; when the review purpose changes, a new stage begins.
• The first round of each independent review stage must have a fresh reviewer created by the current main flow, remaining independent of the implementer; the reviewer executes a single round of cs-review, and must not create sub-agents internally.
• After the main flow processes findings, it first fixes and re-runs verification, then freezes the new complete review target; for fixes arising solely from processing findings, the re-review must continue the same session of the same reviewer as a follow-up. The re-review simultaneously checks the complete current candidate and this round's fix increment, reporting each item resolved / unresolved / new findings; it must not merely check off old findings or mechanically tick boxes. Reviewer independence requires it to be independent of the implementer, not to have amnesia about its own previous review round.
• Within the same review stage, a maximum of 3 rounds with final-status reports may accumulate; changing the reviewer does not reset the count. The reviewer may be changed only when the original run/session fails or is unrecoverable, capabilities are insufficient, the goal, scope, design, or core path undergoes a major change, the reviewer declares it can no longer judge independently, or the owner requests a second opinion; when changing, create a fresh reviewer. If the limit is exceeded and blocking issues or disagreements remain, submit to the user for adjudication, and do not continue additional rounds or claim completion.
• continuous and per-item policy, only one current_itemis allowed at a time; this is a serial constraint, not a manual gate for each sub-item.item_progression: parallel , the main flow is the sole orchestrator and sole cursor writer, and may simultaneously advance multiple approved sub-items whose dependencies are satisfied: concurrent sub-items are delegated as workers to isolated workspaces provided by the host, and the concurrent set is recorded in the cursor active_items; scheduling, delegation contracts, the single-writer invariant, serial integration, and capability fallback are executed per references/parallel-execution.md , read only when that policy is in effect.active and a valid approval hash indicates that approved sub-items may be executed; after resumption, continue with the cursor policy without re-asking whether to continue.
• After a sub-item passes the assurance and verification selected by its owning skill, per milestone_commit , condense the code, evidence, and work cursor update into one semantic atomic milestone, and do not pile multiple sub-items into the same diff.item_progression: continuous , after a non-final sub-item is completed, automatically select the first incomplete sub-item in the permanent document order whose dependencies are satisfied, update current_item / next_action, and continue execution in the same entrusted main flow; when incomplete sub-items remain but no runnable candidate exists, pause as blocked.item_progression: parallel , after workers deliver in isolated workspaces, the main flow integrates serially in completion order: merge each item in a way that does not advance the main history, re-run that sub-item's authoritative verification on the merged result, and only after verification passes create the semantic atomic milestone commit; each time an item is integrated, newly ready sub-items are issued; parallelism permits concurrency but does not mandate it, and when neither all qualified worker creation capabilities nor isolation capabilities are available, degrade within this session to serial advancement without changing the cursor policy fields, and explain this in the report. Do not ask "whether to continue to the next item," and do not treat ordinary sub-item completion as a final return.
• item_progression: per-item , after completing the current milestone, pause according to the recorded per-item checkpoint policy; it is a behavior chosen by the owner at the first gate or in a subsequent explicit change, and must not be disguised as the default continuous mode.milestone_commit: manual , deliver only a committable checkpoint, and do not commit on your own.
• remote_publish: each-milestone , publish after each semantic atomic commit according to the branch/remote strategy already determined by the project, host, or owner;final , publish once after integration verification and final acceptance review pass and before requesting the owner's final acceptance;manual the agent does not perform remote publishing. When branch/remote is not explicit, pause to request context and do not choose on its own; when publishing fails, write blocked_by and pause, do not silently continue.
• Epic orchestration adds a pause only in the following situations: contract or major risk changes, blockers/product decisions that cannot be resolved on its own, newly added permissions, important findings that require explicit owner acceptance, review exceeding limits with disagreements remaining, missing or invalid legacy cursor strategy, the user explicitly requesting a pause, and the final owner gate after all sub-items are complete. The confirmation thresholds of the sub-item owning skill take effect as usual; when an approved sub-item contract covers the same decision, do not confirm again, and newly arising risks that would change the outcome are still handled per the owning skill or Epic re-confirmation.
• After a reviewer is created, bind it to that run and record the run identity: it is healthy when the target is valid, the capability still satisfies requirements, and the reviewer status is running, or when Awaiting carries the same queryable run identity and the query is still active; when the status is healthy, wait for the terminal report, and do not cancel, recreate, or send in parallel just because a better creation method is later discovered. Only when the run explicitly fails or terminates without a report, is idle / Awaiting with no recoverable run identity, the capability does not satisfy requirements, or the target is invalid, does this round fail and not count as a round; do not blindly resend, first check the task packet and agent status, then decide on one bounded retry, changing the creation method, or handing it to the user.
• Each sub-item is executed according to the discipline of its type (the thresholds of cs-feat / cs-issue / cs-refactor take effect as usual); upon completion, update the work cursor's ID progress, evidence, and commit pointer; when documents and facts are inconsistent, take repository facts as authoritative and correct the documents.
• After all sub-items are complete, set phase to acceptance and run integration verification. Final acceptance is an independent review stage and must be started by the current main flow by separately creating a fresh reviewer with a new lineage; it must not reuse the reviewer lineage of sub-items, prior design review, or contract review; it performs cs-review audit/acceptance review against the latest acceptance criteria already approved by the owner. The main flow handles this stage's findings according to the same lineage, and after the threshold passes, provides each sub-item's result, verification evidence, and remaining items,does not perform overall acceptance on behalf of the user, and stops to wait for the owner's final acceptance.

Wrap-up

• After the owner accepts, first write the final scope, key decisions, delivery index, overall acceptance, remaining risks, and graduation checklist into the permanent Epic, then use terminal-state updates to set accepted and remove the work pointer. Stable product contracts go into canonical requirement/project documents, structural decisions go into ADRs, and lessons go into lessons; when the target location does not exist, ask the owner to choose, and until it is determined, keep the conclusion in the permanent Epic.
• Terminal state accepted / superseded / cancelled is a persistent signal that execution cannot be resumed. Regardless of whether the work pointer, cursor, or the owning sub-item's work remains at interruption, idempotently continue from repository facts: complete the terminal-state record and graduation checklist, remove the pointer, delete the Epic cursor, and then according to frontmatter epic: clean up all sub-item work; do not resume execution or create a duplicate Epic, and the permanent Epic document must not be deleted.
• Do not restore the cs-goal entry, goal package,state.yaml, per-round iteration reports or legacy runtime gates; the target contract, recovery cursor, owner gate, and final-state acceptance are all handled by the above two-layer documents.