software-engineering-workflow-skill

What this skill does

# 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 audib