software-engineering-workflow-skill

name	software-engineering-workflow-skill
description	Run a staged software-engineering delivery feedback loop from bootstrap through investigation, requirements, design, runtime review, implementation, API/E2E and executable validation, code review, docs sync, and final handoff with durable artifacts and explicit re-entry.

Software Engineering Workflow Skill

Overview

Run a staged software-engineering delivery workflow for software changes: bootstrap ticket context, investigate and refine requirements, build design and future-state runtime artifacts, drive implementation with one implementation artifact that carries both a stable baseline and live progress tracking, validate behavior with API/E2E and other executable validation evidence appropriate to the system, apply independent code review, synchronize long-lived docs, and finish with explicit user-verified handoff and repository finalization. For medium/large scope, include a full proposed design document organized by data-flow spine inventory, ownership, off-spine concerns, and derived separation of concerns. This workflow is stage-gated. Do not batch-generate all artifacts by default. In this skill, future-state runtime call stacks are future-state (to-be) execution models. They are not traces of current (as-is) implementation behavior.

Skill Layout

• SKILL.md is the workflow router. It defines the stage rules and points each stage to its owned templates/references.
• shared/ stores cross-stage references that multiple stages reuse:
  • shared/design-principles.md
  • shared/workflow-state-template.md
• stages/ stores stage-owned templates and references:
  • stages/00-bootstrap/
  • stages/01-investigation/
  • stages/02-requirements/
  • stages/03-design/
  • stages/04-future-state-runtime-call-stack/
  • stages/05-future-state-runtime-call-stack-review/
  • stages/06-implementation/
  • stages/07-api-e2e/
  • stages/08-code-review/
  • stages/09-docs-sync/
  • stages/10-handoff/
• Keep stage-specific material in the matching stage folder. Use shared/ only for genuinely cross-stage references.
• When a stage has a local guide or checklist, use that stage-owned file first before falling back to generic workflow prose.

Terminology

• Subsystem / capability area: a larger functional area that owns a broader category of work and may contain multiple files plus optional module groupings.
• Module: an optional intermediate grouping inside a subsystem when the codebase benefits from it. In this skill, module is not a synonym for one file or the default ownership term.
• Folder / directory: a physical grouping used to organize files and any optional module groupings.
• File: one concrete source file and the primary unit where one concrete concern should land.

Workflow

Ticket Folder Convention (Project-Local)

• For each task, create/use one ticket folder under tickets/in-progress/.
• Folder naming: use a clear, short kebab-case name (no date prefix required).
• Write all task planning artifacts into the in-progress ticket folder while work is active.
• Standard states:
  • active work path: tickets/in-progress/<ticket-name>/
  • completed archive path: tickets/done/<ticket-name>/
• Move rule (mandatory): move a ticket from in-progress to done only when the user explicitly confirms completion (for example: "done", "finished", or "verified") or explicitly asks to move it.
• Final archive ordering rule (mandatory): when explicit user completion/verification also triggers repository finalization, move the ticket folder to tickets/done/<ticket-name>/ before the final commit so the committed state includes the archived ticket path.
• Reopen rule (mandatory): if the user asks to continue/reopen a completed ticket, move it from tickets/done/<ticket-name>/ back to tickets/in-progress/<ticket-name>/ before making new updates.
• Never auto-move a ticket to done based only on internal assessment.
• If the user specifies a different location, follow the user-specified path.

Ticket + Worktree Bootstrap (Mandatory First Action)

• Before investigation, bootstrap work context in this order:
  • create/use tickets/in-progress/<ticket-name>/,
  • if the project is a git repository:
    • resolve the bootstrap base branch from explicit user instruction when provided; otherwise infer the tracked remote default/integration branch with highest confidence,
    • when creating a new ticket worktree/branch, refresh tracked remote refs first so bootstrap starts from the latest remote state instead of a stale local head,
    • create/reuse a dedicated ticket worktree for the ticket branch before writing artifacts,
    • when creating a new ticket branch, create codex/<ticket-name> from the latest tracked remote base branch,
  • create/update requirements.md with status Draft from user-provided requirement intent.
• Investigation must not start before the ticket bootstrap and requirements.md Draft are physically written.
• If a dedicated worktree already exists for the ticket, reuse it instead of creating a new one.
• If the user specifies a base branch, always use the latest tracked remote state of that branch rather than guessing from a local copy.
• If remote refresh or base-branch resolution fails, keep Stage 0 Blocked and record the blocker before investigation.
• If the environment is not a git repository, continue without worktree setup and still enforce ticket-folder + Draft requirement capture.

Workflow State File (Mandatory Enforcement Artifact)

• Create and maintain tickets/in-progress/<ticket-name>/workflow-state.md as the canonical stage-control artifact.
• Initialize it during Stage 0 immediately after ticket bootstrap with:
  • Current Stage = 0,
  • Code Edit Permission = Locked,
  • Stage 0 Bootstrap Record filled with bootstrap mode plus, when git repo, requested base branch if any, resolved base remote/base branch, remote-refresh result when performed, worktree path, and ticket branch,
  • stage gate rows in Not Started/In Progress state.
• Update model (mandatory):
  • rewrite Current Snapshot in place on every stage transition,
  • append one row to Transition Log for every transition/re-entry,
  • keep Stage Gates rows current with evidence links/paths.
• Source-code edit lock (hard rule):
  • no source code edits are allowed unless workflow-state.md explicitly shows Code Edit Permission = Unlocked,
  • default state is Locked; unlock source-code edits only when Stage 6 prerequisites are satisfied.
• Re-entry lock rule:
  • on any Stage 7/8 failure, set Code Edit Permission = Locked before re-entry actions,
  • record trigger/classification/return path in workflow-state.md before proceeding.
• Violation protocol:
  • if source code is edited while Code Edit Permission = Locked, record a violation entry in workflow-state.md,
  • pause further source edits, declare re-entry, and return to the required upstream stage path.

Audible Notifications (Speak Tool, Required)

• Use the Speak tool for workflow-state transition updates so the user can follow where execution is and what is next.
• Playback rule (mandatory): for required audible notifications, call Speak with play=true explicitly.
• Do not set play=false by default for required transition notifications.
• Exception: set play=false only when the user explicitly requests silent mode.
• Transition-driven speak rule (mandatory):
  • speak only when workflow-state.md is updated for a stage transition, gate decision, re-entry decision, or code-edit lock/unlock change,
  • do not speak for low-level command execution, intermediate analysis notes, or partial drafts.
• Required audible events:
  • workflow kickoff (task accepted, next stage),
  • every stage transition (From Stage -> To Stage) after workflow-state.md transition log is appended,
  • every gate decision (Pass/Fail/Blocked) after gate evidence is written,
  • every re-entry declaration (classification + return path) after workflow-state.md re-entry section is updated,
  • every Code Edit Permission change (Locked/Unlocked) after snapshot update.
• Speak ordering rule:
  • update workflow-state.md first,
  • then emit audible notification reflecting the persisted state.
• Spoken message content (mandatory):
  • current stage,
  • what just completed/changed (transition or gate result),
  • next stage/action,
  • code-edit lock state when it changed.
• If multiple transitions happen close together, batch them into one short message after the final persisted update.
• Keep each spoken message short (1-2 sentences), status-first, and action-oriented.
• If the Speak tool fails or is unavailable, continue the workflow and provide the same update in text.
• Do not speak secrets, tokens, or full sensitive payloads.

Execution Model (Strict Stage Gates)

• Work in explicit stages and complete each gate before producing downstream artifacts.
• Before every stage transition, update workflow-state.md first (snapshot + transition log + gate statuses), then proceed.
• Treat workflow-state.md as an execution lock controller, not optional documentation.
• Transition authority rule (mandatory): stage movement is controlled by the Stage Transition Contract + Transition Matrix. When a trigger condition is met, transition immediately to the mapped path; do not continue in the current stage by preference.
• Transition Execution Rule (mandatory): whenever workflow-state.md is updated to declare a stage transition or classified re-entry, immediately enter and execute the target stage by default, without waiting for another user message. Recording the transition and describing the next step is not sufficient. The transition is not complete until work has actually resumed in the target stage. Stop only for a real blocker or an explicit user-only gate.
• Requirements can start as rough Draft from user input/bug report artifacts before deep analysis.
• Do not start investigation until ticket/worktree bootstrap is complete and requirements.md status Draft is physically written.
• Do not mark understanding pass complete until investigation-notes.md is physically written and current for the ticket.
• Do not draft design artifacts (proposed-design.md or small-scope solution sketch in implementation.md) until deep understanding pass is complete and requirements.md reaches Design-ready.
• Do not finalize implementation.md baseline sections or start execution tracking sections until the future-state runtime call stack review gate is fully satisfied for the current scope.
• Do not start implementation execution until implementation.md baseline is finalized and its execution-tracking sections are initialized.
• Do not start source-code edits until all of the following are true in workflow-state.md:
  • Current Stage = 6,
  • Code Edit Permission = Unlocked,
  • Stage 5 gate is Go Confirmed,
  • required upstream artifacts are marked Pass with evidence.
• Do not start Stage 7 executable-validation implementation and execution until implementation execution is complete with required unit/integration verification and Stage 6 modernization/ownership-dependency checks are satisfied.

Canonical Stage Sequence (Quick Map)

Stage	Name	Core Deliverable/Gate	Code Edit Permission
0	Bootstrap + Draft Requirement	Ticket/worktree bootstrap complete (ticket path + if git repo: base branch resolved from tracked remote, remote freshness handled for new bootstrap, dedicated ticket worktree/branch created or reused) + requirements.md = Draft	Locked
1	Investigation + Triage	investigation-notes.md current + scope triage complete	Locked
2	Requirements Refinement	requirements.md reaches Design-ready/Refined	Locked
3	Design Basis	implementation.md solution sketch (Small) or proposed-design.md (Medium/Large)	Locked
4	Future-State Runtime Call Stack	future-state-runtime-call-stack.md current	Locked
5	Future-State Runtime Call Stack Review	Go Confirmed (two consecutive clean rounds with no blockers/persisted updates/new use cases)	Locked
6	Source Implementation + Unit/Integration	Source code + required unit/integration checks complete + no backward-compat/legacy retention + ownership-driven dependency quality preserved + Authoritative Boundary Rule preserved + touched files correctly placed	Unlocked
7	API/E2E + Executable Validation Gate	executable validation scenarios implemented and acceptance-criteria + spine coverage closure complete	Unlocked
8	Code Review Gate	Code review decision recorded (Pass/Fail) with <=500 effective-line hard-limit on changed source files only + required >220 delta-gate assessments on changed source files only + data-flow spine inventory/ownership/off-spine concern checks + existing-capability reuse + reusable-owned-structure extraction + shared-structure/data-model tightness + shared-base coherence + repeated-coordination ownership + empty-indirection + scope-appropriate separation of concerns + ownership-driven dependency quality + Authoritative Boundary Rule preservation + file placement within the correct subsystem and folder, with any optional module grouping justified + flat-vs-over-split layout judgment + interface-boundary clarity + naming quality across files/folders/APIs/types/functions/parameters/variables + naming-to-responsibility alignment + no unjustified duplication of code/repeated structures in changed scope + patch-on-patch complexity control + test quality + test maintainability + validation-evidence sufficiency + no-backward-compat/no-legacy checks

Stage Transition Contract (Enforcement)

Stage	Exit Condition (Must Be True To Transition)	On Fail/Blocked	Next Stage On Pass
0 Bootstrap + Draft Requirement	Ticket/worktree bootstrap is complete, the base branch/worktree decision is recorded, and requirements.md status is Draft	Stay in 0 until bootstrap is complete	1
1 Investigation + Triage	investigation-notes.md is current and scope triage (Small/Medium/Large) is recorded	Stay in 1 until investigation evidence is complete	2
2 Requirements	requirements.md is Design-ready (or Refined) with requirement/acceptance-criteria coverage maps	Stay in 2 until requirements are design-ready	3
3 Design Basis	Design basis artifact is current (implementation.md solution sketch for Small, proposed-design.md for Medium/Large)	Stay in 3 and revise design basis	4
4 Future-State Runtime Call Stack	future-state-runtime-call-stack.md is current for in-scope use cases	Stay in 4 and regenerate the future-state runtime call stack	5
5 Future-State Runtime Call Stack Review	Future-state runtime call stack review reaches Go Confirmed (two consecutive clean rounds with no blockers, no required persisted artifact updates, and no newly discovered use cases)	Classified re-entry before next review round (Design Impact: 3 -> 4 -> 5, Requirement Gap: 2 -> 3 -> 4 -> 5, Unclear: 1 -> 2 -> 3 -> 4 -> 5)	6
6 Source + Unit/Integration	Source implementation complete, required unit/integration checks pass, no backward-compatibility/legacy-retention paths remain in scope, ownership-driven dependencies remain valid (no new unjustified cycles/tight coupling), the Authoritative Boundary Rule remains valid (no new bypass of authoritative boundaries), and touched files sit in the correct folder under the correct owning subsystem

Transition Matrix (Pass/Fail/Blocked)

Trigger	Required Transition Path	Notes
Normal forward pass	0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8 -> 9 -> 10	Use only when each stage gate is Pass.
Stage 5 blocker classified Design Impact	3 -> 4 -> 5	Use when issue is clearly in spine/ownership/off-spine concern/boundary/naming decisions.
Stage 5 blocker classified Requirement Gap	2 -> 3 -> 4 -> 5	Use when missing/ambiguous requirement or acceptance criteria is discovered.
Stage 5 blocker classified Unclear	1 -> 2 -> 3 -> 4 -> 5	Use when root cause is uncertain or cross-cutting and investigation must be refreshed first.
Stage 6 failure classified Local Fix	stay in Stage 6	Fix implementation/tests within Stage 6; do not advance to Stage 7.
Stage 6 failure classified Design Impact	1 -> 3 -> 4 -> 5 -> 6	Re-open investigation checkpoint, then re-enter design/runtime chain before continuing implementation.
Stage 6 failure classified Requirement Gap	2 -> 3 -> 4 -> 5 -> 6	Update requirements first, then rerun downstream chain before continuing implementation.
Stage 6 failure (Unclear/cross-cutting root cause)	0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6	Re-open Stage 0 controls in the same ticket context, then rerun full chain before continuing implementation.
Stage 7 failure classified Local Fix	6 -> 7	Update artifacts first, then code fix, then rerun Stage 7 scenarios.
Stage 7 failure classified Design Impact	1 -> 3 -> 4 -> 5 -> 6 -> 7	Re-open investigation, then re-enter design/runtime chain before retrying Stage 7.
Stage 7 failure classified Requirement Gap	2 -> 3 -> 4 -> 5 -> 6 -> 7	Update requirements first, then rerun downstream chain.

0) Bootstrap Ticket + Capture Draft Requirement

• Use stages/00-bootstrap/bootstrap-checklist.md.
• Run mandatory first-action sequence:
  • create/use tickets/in-progress/<ticket-name>/,
  • if git repo, resolve bootstrap base branch from explicit user instruction when provided; otherwise infer the tracked remote default/integration branch with highest confidence,
  • if git repo and a new ticket worktree/branch is needed, refresh tracked remote refs first,
  • if git repo, create/reuse dedicated ticket worktree for codex/<ticket-name>; when creating a new ticket branch, branch it from the latest tracked remote base,
  • create/update tickets/in-progress/<ticket-name>/workflow-state.md from shared/workflow-state-template.md, set Current Stage = 0, Code Edit Permission = Locked, and fill Stage 0 Bootstrap Record,
  • capture initial requirement snapshot (requirements.md status Draft) from user input/bug report evidence first (text, images, logs, repro notes, constraints).
• Do not run deep investigation before Stage 0 bootstrap and requirements.md Draft are physically written.
• If remote refresh, base-branch resolution, or ticket-worktree creation fails, keep Stage 0 blocked and record the failure in workflow-state.md instead of falling back to a stale local branch.
• Before transitioning to Stage 1, update workflow-state.md snapshot + transition log + stage gate evidence.

1) Investigation + Understanding Pass + Triage

• Use stages/01-investigation/investigation-guide.md.
• Create/update tickets/in-progress/<ticket-name>/investigation-notes.md continuously during investigation. Treat it as a durable evidence log, not a brief summary. Do not keep investigation results only in memory.
• Investigation is not read-only: when needed to establish current behavior or isolate root cause, actively reproduce the issue, run focused commands/tests, write small diagnostic scripts, add temporary probes/instrumentation, perform the minimal environment setup or mocks needed to observe the problem, read public APIs/specs/issues, and inspect or clone upstream/vendor/sample repositories when that is the practical way to gather evidence.
• Treat Stage 1 methods as problem-dependent and non-exhaustive: use whatever bounded evidence-gathering work is needed to reduce uncertainty and verify assumptions before design.
• Minimum codebase understanding pass before design:
  • identify entrypoints and execution boundaries for in-scope flows,
  • identify touched files, affected modules/subsystems, and owning concerns,
  • identify expected canonical file locations/folder owners for touched concerns (for example: platform-specific vs shared),
  • identify current naming conventions (subsystem names, file names, optional module names when relevant, API style),
  • identify unknowns that could invalidate design assumptions.
• In investigation-notes.md, record in enough detail that later stages can reuse the investigation without repeating the same major search/research work unless the facts have changed:
  • investigation goals/questions,
  • detailed source log (local file paths, web links, open-source references, papers, exact commands run, and search queries when those materially shaped the result),
  • key findings, constraints, and observed behavior tied back to the exact source used,
  • codebase findings with exact files/symbols/entrypoints/owners where relevant,
  • file-placement observations (which files are already under the right owning folder, which are misplaced, and what the canonical location should be),
  • runtime/probe findings when reproductions, traces, or scripts were used,
  • reproduction prerequisites and environment/setup details when those materially affected the investigation outcome,
  • external dependency, public API, upstream-source, issue-tracker, or sample-app findings when those materially shaped the understanding,
  • open unknowns/questions,
  • implications for requirements/design.
• Prefer structured, detailed notes over compressed summaries. Use short synthesis sections for readability, but keep enough concrete evidence in the artifact that later stages do not need to rediscover the same facts from scratch.

2) Refine Requirements Document To Design-Ready (Mandatory)

• Use stages/02-requirements/requirements-refinement-guide.md.
• Create/update tickets/in-progress/<ticket-name>/requirements.md for all sizes (Small, Medium, Large).
• Requirement writing is mandatory even for small tasks (small can be concise).
• Use one canonical file path only: update requirements.md in place. Do not create versioned duplicates such as requirements-v2.md.
• Requirements maturity flow:
  • Draft: rough capture from report/input evidence,
  • Design-ready: refined after deep understanding pass,
  • Refined: further updates when design/review/implementation feedback reveals gaps.
• Minimum required sections in requirements.md:
  • status (Draft/Design-ready/Refined),
  • goal/problem statement,
  • in-scope use cases,
  • acceptance criteria,
  • constraints/dependencies,
  • assumptions,
  • open questions/risks.
• Requirements quality rule (mandatory): requirements must be verifiable behavior specifications, not only descriptive narratives.
• For each requirement, include a stable requirement_id and explicit expected outcome.
• For each acceptance criterion, include a stable acceptance_criteria_id (for example: AC-001) and an explicit measurable expected outcome.
• Acceptance criteria must be testable and cover primary behavior plus relevant edge/error behavior.
• Include a requirement coverage map to call-stack use cases (all requirements must map to at least one use case).
• Include an acceptance-criteria coverage map to Stage 7 scenarios (all acceptance criteria must map to at least one executable validation scenario).
• Confirm the triage result (Small vs Medium vs Large) and rationale in the requirements doc.
• Refine requirements from the latest investigation-notes.md; do not derive requirements from memory-only investigation.
• Design-ready requirement gate must make expected behavior clear enough to draft design and runtime call stacks.
• If understanding is not sufficient to reach Design-ready, continue understanding pass and refine requirements first.

Core Modernization Policy (Mandatory)

• Mandatory stance: no backward compatibility and no legacy code retention.
• Do not preserve legacy behavior, legacy APIs, compatibility wrappers, dual-write paths, or fallback branches kept only for old flows.
• Prefer clean replacement and explicit deletion of obsolete code, files, tests, flags, and adapters in the same ticket.
• Do not add compatibility exceptions in this workflow.

Shared Design Principles (Design + Review, Mandatory)

• Design and review must use the same principles and vocabulary. Review is a check of design quality, not a different rule system.
• Use shared/design-principles.md as the shared reference for Stage 3 design work, Stage 5 review, and Stage 8 structural review.
• shared/design-principles.md also carries the derived applied workflow, structural triggers, local mechanisms, and example shapes that were previously split into a second helper file.
• Use stages/08-code-review/code-review-principles.md as the Stage 8 review reference.
• The core principles are:
  • data-flow spine inventory and clarity,
  • ownership clarity and boundary encapsulation,
  • off-spine concerns around the spine.
• Separation of concerns is still mandatory, and in this workflow it should become stronger, not weaker. The difference is ordering: start with spine and ownership, then decompose concerns around that structure so each boundary stays coherent.
• Ownership is the concrete form of separation of concerns: if a concern has no clear owner, the structure is wrong.
• Dependency direction follows ownership. State allowed directions and forbidden shortcuts explicitly when design risk exists.
• Authoritative Boundary Rule (mandatory): when one boundary is the authoritative public entrypoint for a domain subject, callers above it should depend on that boundary rather than on both the boundary and one of its internal owned mechanisms at the same time. This is the no boundary bypass / no mixed-level dependency rule.
• If callers only bypass an internal concern because the outer boundary does not expose enough usable API, strengthen that authoritative boundary or redesign the ownership split explicitly instead of normalizing the bypass.
• Off-spine concern reuse follows ownership too. Before adding a new helper or off-spine concern, check whether an existing capability area or subsystem already owns that responsibility.
• Spine, owner, and off-spine concern are architecture relationship terms, not naming templates. Do not literalize them into file, folder, class, service, or type names.
• Module placement and file placement follow ownership. If a file's path no longer matches the real concern, move, split, or rename it instead of rationalizing the mismatch.
• Subsystem, folder, and file mapping should be spine-led and ownership-led, but not mechanical. Optional module groupings are secondary structure only when they make boundaries easier to read.
• Distinct structural depths often deserve distinct folders, but do not force artificial over-splitting. If a flatter layout is clearer, justify it explicitly.

3) Draft The Proposed Design Document

• Required for Medium/Large. Optional for Small.
• Prerequisite: requirements.md is Design-ready (or Refined) and current for this ticket.
• For Small, do not require a full proposed design doc; use the draft implementation.md solution sketch as the lightweight design basis for runtime call stacks.
• Architecture-first rule: define the target architecture shape before mapping work onto existing files.
• Design from the data-flow spine first:
  • identify the primary execution/data-flow spine(s),
  • enumerate all relevant spines that matter to understanding the design,
  • name the main domain subject nodes on each spine,
  • define what each main-line node owns,
  • identify off-spine concerns that serve those owners,
  • check whether those off-spine needs should reuse or extend existing capability areas/subsystems before creating anything new,
  • record the return/event spine(s) when the change is async or event-driven,
  • record bounded local/internal spines when a loop, worker cycle, state machine, or dispatcher materially shapes one owner's behavior.
• Separation-of-concerns rule (mandatory): once the spine and owners are clear, split off-spine responsibilities so each main node and each off-spine concern remains self-encapsulated. Do not overload one spine node with every concern just because it sits on the main line.
• Authoritative Boundary Rule (mandatory): identify which boundaries are authoritative public entrypoints versus internal owned sub-layers. Callers above an authoritative boundary should not depend on both that boundary and one of its internal managers, repositories, helpers, or lower-level concerns at the same time.
• Do not anchor design to current file layout when the layout is structurally wrong for the target behavior.
• File-placement rule (mandatory): target file paths must match owning concern/boundary/platform; if a file is codex-specific, cloud-specific, UI-specific, infra-specific, or otherwise scope-bound, place it in that canonical area instead of near whichever caller currently imports it.
• Folder-layout rule (mandatory): map subsystems/folders/files from the spine and ownership model, and add optional module groupings only when they materially help readability rather than by default. Do it with judgment rather than as a rigid one-folder-per-step projection. If a flatter layout is clearer, justify it. If a split is proposed, it should reflect a real owner or boundary.
• Interface-boundary rule (mandatory): design APIs, queries, commands, and reused service methods around explicit subject ownership and explicit identity shape. Do not use one generic boundary that accepts an ambiguous ID or generic selector and guesses whether the subject is, for example, an agent run, team run, or team member run.

4) Build Future-State Runtime Call Stacks Per Use Case

• Required for all sizes (Small, Medium, Large).
• For Small, keep it concise but still cover each in-scope use case with primary path plus key fallback/error branch when relevant.
• Basis by scope:
  • Small: use the draft implementation.md solution sketch as the design basis.
  • Medium/Large: use the proposed design document as the design basis.
• For each use case, write a future-state runtime call stack from entry point to completion in a debug-trace format.
• Use stable use_case_id values and ensure IDs match the design coverage matrix and review artifact.
• For each use case, record mapped spine ID(s), spine scope, and governing owner from the design basis.
• Use two allowed use-case source types:
  • Requirement: derived from explicit requirement behavior.
  • Design-Risk: derived from architecture or technical risk that must be validated.
• Coverage rule (mandatory): every in-scope requirement must be covered by at least one Requirement use case.
• For each Design-Risk use case, record the technical objective/risk justification and expected observable outcome.
• Treat this artifact as to-be architecture behavior derived from the proposed design (or small-scope solution sketch), not as-is code tracing.
• If current code differs from target design, model the target design behavior and record migration/transition notes separately.
• Include file and function names at every frame using path/to/file.ts:functionName(...).
• Show architectural boundaries explicitly (e.g., controller -> service -> repository -> external API).
• Include primary path and fallback/error paths, not only happy path.
• Include explicit use-case coverage status per use case (primary/fallback/error) and mark intentional N/A branches.
• If a use case exercises a bounded local spine, make that explicit instead of hiding it inside a generic end-to-end stack.
• Mark async/event boundaries (await, queue enqueue/dequeue, worker loop handoff).
• Mark state mutations and persistence points (in-memory state, cache write, DB/file write).
• Capture decision gates and conditions that choose one branch over another.

5) Review Future-State Runtime Call Stacks (Future-State + Architecture + Naming + Cleanliness Gate)

• Create future-state-runtime-call-stack-review.md as a mandatory review artifact.
• Review focus is future-state correctness and implementability against the target design basis (proposed-design.md for Medium/Large, small-scope solution sketch in implementation.md for Small), not parity with current code structure.
• Review must challenge architecture choice itself (spine/ownership/off-spine concerns/allocation), not only file-level separation of concerns.
• Review must reuse the same shared design principles from Stage 3; do not apply a different principle set in review.
• Review must explicitly verify file placement against the Stage 3 design basis; wrong folder placement is a structural defect, not a cosmetic nit.
• Review must explicitly judge whether the proposed layout is readable for the scope or whether it is either too flat or too artificially fragmented.
• Review must explicitly check example-based clarity when the design uses examples or when the design would otherwise stay too abstract.
• Run review in explicit rounds and record each round in the same review artifact.
• In every round, run a dedicated missing-use-case discovery sweep before verdicting the round.
• Review each use case against these criteria:
  • architecture fit check (Pass/Fail): chosen architecture shape is appropriate for this use case and expected growth,
  • data-flow spine clarity check (Pass/Fail): the main end-to-end motion and any bounded local spines are readable and not fragmented across peer coordinators,
  • spine inventory completeness check (Pass/Fail): all relevant spines are explicitly named with clear start/end boundaries and owner relationships,
  • ownership clarity check (Pass/Fail): main-line nodes and off-spine concerns have clear owners with concrete authority,
  • off-spine concern clarity check (Pass/Fail): off-spine concerns serve the spine without competing with it or owning hidden sequencing,
  • boundary placement check (Pass/Fail): responsibilities are assigned to the right owner or subsystem boundary,
  • ownership-driven dependency check (Pass/Fail): dependencies follow ownership, avoid tight cross-subsystem coupling, and avoid unjustified cyclic cross-references,

6) Implement Source + Unit/Integration And Track Progress

• Use a bottom-up, test-driven approach: implement foundational dependencies first.
• Sequence is mandatory:
  • first ensure implementation.md baseline is finalized,
  • then initialize/update the execution-tracking sections in implementation.md,
  • then execute source implementation with required unit/integration verification.
• Stage separation rule (mandatory):
  • Stage 6 implements source code and verifies file and service boundaries, while preserving readable subsystem grouping, with unit/integration tests.
  • Stage 7 implements executable validation assets and runs the mapped Stage 7 scenarios against acceptance criteria.
  • Stage 8 runs the code review gate after Stage 7 passes.
• Include requirement traceability in plan/progress (requirement -> design section -> call stack/use_case -> implementation tasks/tests).
• Include spine traceability in plan/progress (spine -> owner -> use case -> implementation tasks -> validation scenarios).
• Integration test coverage is required for behavior that crosses module boundaries, process boundaries, storage boundaries, or external API boundaries. If any such behavior is not covered, record a concrete rationale.
• Finalize planning artifacts before kickoff:
  • Small: refine the draft implementation.md solution sketch until future-state runtime call stack review passes final stability gate (Go Confirmed).
  • Medium/Large: create implementation.md only after future-state runtime call stack review passes final stability gate (Go Confirmed).
• Initialize the execution-tracking sections in implementation.md at implementation kickoff, after required pre-implementation artifacts are ready (including the proposed design document for Medium/Large).
• One merged implementation artifact with both baseline planning and live tracking is required for all sizes (Small, Medium, Large).
• Keep detailed Stage 7, Stage 8, and Stage 9 records in their own canonical artifacts. implementation.md should carry only implementation-owned planning/tracking plus downstream handoff inputs and short status pointers.
• Treat future-state runtime call stack + review as a pre-implementation verification gate: ensure each use case is represented and reviewed before coding starts.
• Start implementation only after the review gate says implementation can start and all in-scope use cases are .

7) Implement API/E2E And Other Executable Validation And Run Stage 7 Gate (Mandatory)

• Run this stage immediately after Stage 6 completes.
• At Stage 7 entry, update workflow-state.md and keep Code Edit Permission = Unlocked while Stage 7 validation artifacts are being implemented/executed.
• Create/update tickets/in-progress/<ticket-name>/api-e2e-testing.md as the canonical scenario + result artifact.
• Multi-round artifact rule (mandatory): keep one canonical api-e2e-testing.md path for the ticket. Do not create versioned copies by default. On every rerun, check prior unresolved failures first, then continue validation. The latest round result is authoritative; earlier rounds remain history.
• Round-resolution rule (mandatory): on Stage 7 round >1, update the prior-failure resolution check before declaring the new gate result.
• Stage 7 scope includes:
  • implementing durable repo-resident validation assets as needed,
  • implementing API, browser/UI, native desktop/UI, CLI, process/lifecycle, integration, multi-service, or multi-node harnesses as needed,
  • executing Stage 7 scenarios mapped from acceptance criteria.
• Durable validation-first rule (mandatory): first implement or update the validation tests, harnesses, and assets that should live in the repository and govern future changes.