implementation-workflow

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Implementation Workflow

Carry one cohesive feature or behavior change from task definition through design, implementation, verification, independent review, and documentation. Perform the implementation directly to retain end-to-end context, and use a living Implementation Note to track the work.

## When to Use

Use this workflow for a cohesive feature implementation or behavior change when it involves one or more of:

- non-obvious design decisions
- multiple interacting components or behaviors
- meaningful regression or integration risk
- enough work that a structured workflow and independent review improve reliability

When an ExecPlan exists, apply this workflow within each relevant feature or behavior-change task rather than replacing the ExecPlan.

## Workflow

Maintain the Implementation Note defined below as a concise living record throughout this workflow.

Apply each "Update the Implementation Note" instruction when the step changes state. Do not defer updates until the end.

### 1. Initialize the Implementation Task

Complete substeps 1.1 and 1.2 sequentially. Complete step 1 only after both substeps are complete.

#### 1.1 Define the Task

Define the task goal, in-scope behavior, explicit non-goals, and known constraints before creating the Implementation Note or beginning implementation.

#### 1.2 Create and Initialize the Implementation Note

Create `.agent-work/implementation/{YYYY-MM-DD}-{short-task-name}.md` with a descriptive kebab-case task name using the template below.

If creating `.agent-work/`, create `.agent-work/.gitignore` containing only `*`. Do not modify the repository root `.gitignore`.

Update the Implementation Note: Task Definition and Progress.

### 2. Implement the Change

Perform substeps 2.1 through 2.6 directly and sequentially. Do not delegate design or implementation work. Complete step 2 only after every substep is complete.

#### 2.1 Design the Implementation

Follow `$design-first` to inspect repository evidence and finalize a concrete design covering Behavior, Code Scope, optional Flow, Verification, and material Assumptions and Open Questions. Do not proceed while a question that materially affects implementation remains unresolved.

Update the Implementation Note: Progress and Design.

#### 2.2 Tidy the Existing Implementation if Needed

Use the accepted design to decide whether `$tidy-first` is needed. Apply only small, behavior-preserving tidies that make the change safer or clearer, and verify preserved behavior when practical.

Update the Implementation Note: Progress and Implementation Record > Decisions and Discoveries, Changes, and Verification Results.

#### 2.3 Implement the Behavior

Use `$build-incremental` to implement practical behavior slices, verifying each useful surface and comparing it with the accepted design. If the design becomes incomplete, too broad, or incorrect, pause and revise it before continuing.

Update the Implementation Note: Progress, Design, and Implementation Record > Decisions and Discoveries, Changes, and Verification Results.

#### 2.4 Reassess the Implementation

Review the complete implementation against the goal, scope, preserved behavior, accepted design, and any newly discovered problems, constraints, missing cases, or out-of-scope changes. Return to the appropriate earlier substep when material revision is needed.

Update the Implementation Note: Progress, Design, and Implementation Record > Decisions and Discoveries.

#### 2.5 Simplify the Change

Use `$code-simplify` to remove unnecessary or redundant implementation while preserving intended behavior exactly.

Update the Implementation Note: Progress and Implementation Record > Decisions and Discoveries and Changes.

#### 2.6 Test and Verify

Run verification proportional to risk and scope, covering requested and preserved behavior, relevant failure paths, affected integration points, and broader checks when warranted. Do not complete the step while relevant verification is failing or unperformed without a documented reason.

If verification fails, determine whether it was caused by the current change and return to the earliest affected substep. Keep step 2 incomplete until all relevant failures are resolved and verification is rerun.

Update the Implementation Note: Progress, Design, and Implementation Record > Decisions and Discoveries and Verification Results.

### 3. Review the Implementation

Delegate an independent review to one `code-reviewer`. Provide the reviewer with the Implementation Note, the relevant changes, and the available verification results.

Use the following review cycle:

1. `code-reviewer` reviews the implementation and reports findings.
2. Evaluate the findings and decide the required action.
3. Address accepted findings, update the Implementation Note, and rerun relevant verification.
4. Ask the same `code-reviewer` to verify the resolutions and review the resulting implementation for remaining or newly introduced issues.

Repeat until the `code-reviewer` reports no unresolved findings. Then decide whether to accept the implementation or reopen an earlier step. Keep step 3 incomplete until the implementation is accepted.

If the user explicitly prohibits subagent use, perform the review directly and record that it was not independent.

Update the Implementation Note: Progress, Review, and Implementation Record > Changes and Verification Results.

### 4. Update Documentation if Needed

Determine whether the completed change requires documentation updates.

Update relevant user, developer, API, architecture, workflow, or wiki documentation when needed.

Update the Implementation Note: Progress and Documentation.

### 5. Confirm Completion

Confirm that:

- steps 1 through 4 are complete and the Implementation Note reflects the final state
- the implementation matches the final Task Definition and Design
- verification supports the requested and preserved behavior and relevant failure paths
- the `code-reviewer` reports no unresolved findings

If any condition is unmet, reopen the earliest affected step. Otherwise, mark the task and Implementation Note as complete.

Update the Implementation Note: Status and Progress.

## Implementation Note

From arumaekawa/codex-skills, MIT.

More from arumaekawa/codex-skills