Steadyflow

Steadyflow is a Codex workflow plugin for working safely in existing codebases.

It keeps requirements, implementation, testing, review, and learning connected without forcing every task through the same process. Large changes get a full workflow, small changes stay lightweight, and refactoring starts by locking down behavior that must not change.

Languages

• English
• 한국어

Installation

1. Install The CLI

Install the CLI globally once:

npm i -g steadyflow

2. Initialize A Project

Run init from each target project root:

cd <project>
steadyflow init

This installs or updates user-scope Steadyflow workflow skills and TOML subagents, then creates project knowledge files under:

.steadyflow/

steadyflow init is idempotent. Running it in another project reuses the shared user-scope skills and subagents, then creates that project's .steadyflow/ files.

Restart Codex after init, then use $steadywork, $speedwork, or $refactor.

Optional: Codex Plugin UI

The npm CLI path above installs the usable workflow skills directly into ~/.codex/skills/, so /plugins installation is not required.

If you also want Steadyflow to appear in the Codex plugin marketplace UI, add the public GitHub marketplace:

codex plugin marketplace add Sang-minKIM/steadyflow --ref main

Then install it from the UI:

/plugins

In the OpenAI Codex CLI, open /plugins, search for Steadyflow, then select Install Plugin.

In the Codex app, click Plugins in the sidebar. You should see Steadyflow in the Coding section. Click the + next to Steadyflow and follow the prompts.

For local development from this checkout, register the local marketplace instead:

codex plugin marketplace add .

Maintenance

To inspect, update, or remove installed skills/subagents:

steadyflow doctor
steadyflow update
steadyflow uninstall

To update the global CLI itself:

npm update -g steadyflow

The npm install step does not modify project files. Project files change only when you run steadyflow init or project-scope setup/update commands from a project root.

npm uninstall -g steadyflow does not remove files created under ~/.codex or project .steadyflow/. Use steadyflow uninstall before uninstalling the npm package if you want to remove Steadyflow's user-scope skills and subagents. Project knowledge is preserved by default; remove it explicitly with:

steadyflow uninstall --project-data

Concept

Steadyflow separates explicit workflow-mode skills from execution subagents.

| Principle | Description | | --- | --- | | Skill for workflow | steadywork, speedwork, and refactor are explicit workflow-mode skills that guide the main Codex thread. | | Subagent for focused work | Implementation, review, testing, pattern survey, and learning roles are Codex subagent templates. | | Framer stays main-thread | Requirement analysis and spec drafting stay in the main conversation as workflow-internal framing guidance. | | Project pattern first | Subagents inspect documented project patterns and guardrails before inventing a new approach. | | Behavior preservation | Refactoring changes structure, not behavior. Existing behavior, public contracts, and verification baselines come first. | | Review learning loop | Repeated review findings are converted into future guardrails through Archivist and Surveyor. | | Maintainer release tooling | Plugin releases use changesets and scripts, not user-facing skills. |

Workflow Skills

| Skill | Role | User-facing purpose | | --- | --- | --- | | steadywork | Full workflow mode | Handles broad, multi-step, unclear, risky, or product-sensitive work. | | speedwork | Lightweight workflow mode | Handles small, clear, narrow implementation or bug-fix tasks. | | refactor | Behavior-preserving workflow mode | Handles structure changes where behavior must stay the same. |

framer remains a helper skill used by these workflows in the main thread, but it is not a separate workflow mode.

Workflow Modes

| Workflow | When to use it | Flow | Main rule | | --- | --- | --- | --- | | Steadywork | Larger feature work where requirements, tests, implementation, and review should be separated | Worktree -> Framer full spec -> Scenarist -> step checkpoint reviews -> final full review -> commits | Use fast checkpoint reviews per step and one full review at the final gate or for high-risk steps. | | Speedwork | Small, clear changes with narrow scope | Framer patch note -> optional Surveyor -> optional Redliner -> Craftsman -> Reviewer checkpoint -> commit | Use a patch note and checkpoint review. Escalate to Steadywork or full review if scope or risk grows. | | Refactor | Existing behavior must stay the same while structure improves | Framer refactor note -> optional Surveyor -> baseline or Redliner -> Refiner -> Reviewer full -> commit | Establish the baseline and preserved behavior before Refiner changes code. |

Setup Details

steadyflow init installs workflow skills to ~/.codex/skills/ and custom subagents to ~/.codex/agents/, while project-specific knowledge is stored under .steadyflow/.

Project scope is reserved for advanced subagent overrides. Most projects should share the user-scope skill/subagent definitions and keep project-specific knowledge in .steadyflow/.

Use project scope only when you intentionally want to override the shared subagent definitions for one project.

steadyflow setup --scope project

Project scope installs subagents to .codex/agents/. User scope installs skills to ~/.codex/skills/ and subagents to ~/.codex/agents/.

steadyflow init creates this project knowledge layout:

.steadyflow/
  domain-knowledge.md
  implementation-patterns/
    index.md
  review-playbooks/
    index.md
  lessons/
    archive.md
  runs/              # local, git-ignored run ledgers

Subagents

Subagents are distributed as TOML templates under plugins/steadyflow/assets/subagents/.

| Subagent | Responsibility | Main input | Main output | | --- | --- | --- | --- | | painter | Creates the first publishing-only UI draft for new UI work. | Figma link, Figma MCP address, screenshot, or UI description | UI draft without business logic | | learner | Stores, updates, or removes project domain knowledge. | Explicit user request to remember or correct knowledge | .steadyflow/domain-knowledge.md updates | | scenarist | Writes natural-language test scenarios from an approved spec. | Full spec or refactor scope | TDD or behavior-preservation scenarios | | redliner | Writes test code before production code. | Approved scenarios or verification notes | Failing red-phase tests or refactor baseline tests | | surveyor | Surveys implementation patterns and documents standards, variants, and guardrails. | Whole-project or scoped domain/folder target | Implementation-pattern docs, canonical patterns, guardrails | | craftsman | Implements one approved production-code scope. | Framer artifact, Redliner tests, Surveyor pattern docs | Implementation diff, verification result, pattern-gap notes | | refiner | Improves structure while preserving behavior. | Refactor note, baseline verification, pattern docs | Refactoring diff, before/after verification, tradeoff notes | | reviewer | Reviews implementation or refactoring results in checkpoint or full mode. | Diff, Framer artifact, test output, pattern docs, review mode | Blocking findings, commit or final decision, deferred notes | | archivist | Converts review findings and repeated mistakes into preventive rules. | Reviewer findings, workflow misses | Surveyor guardrail candidates, review playbook rules, archive lessons |

Agent Collaboration

Steadyflow passes each stage's artifact to the next role.

Within one Steadywork run, role subagents can be reused when the next step belongs to the same approved spec, same worktree, and same domain context. Surveyor and Redliner are usually good reuse candidates; Craftsman is reused when consecutive steps stay in the same feature area. Reviewer is usually fresh for independent checkpoint review unless continuity is explicitly useful.

Steadywork also keeps a small local run ledger at .steadyflow/runs/<run-id>/ledger.md so interrupted sessions can resume from file state instead of relying on live subagent context. The ledger should record only resumable state such as current step, active roles, verification/review status, last commit, and next action. Full diffs, logs, and subagent outputs stay out of the ledger.

| Stage | Owner | Purpose | Handoff | | --- | --- | --- | --- | | Frame | framer skill in main thread | Fix the goal, scope, out-of-scope items, and verification criteria. | Spec, patch note, or refactor note | | Scenario | scenarist subagent | Describe expected behavior in natural language. | Test scenarios or behavior to preserve | | Red | redliner subagent | Create tests or a baseline before implementation or refactoring. | Tests that should fail, or baseline tests that should pass | | Craft / Refine | craftsman or refiner subagent | Implement or refactor the selected scope. | Code change, verification result, pattern notes | | Review | reviewer subagent | Find concrete issues in checkpoint or full mode. | Blocking findings, residual risk, deferred full-review notes | | Archive | archivist subagent | Turn repeated mistakes into preventive workflow rules. | Guardrail candidates, review playbook candidates |

Pattern Playbooks

Surveyor documents project-specific implementation patterns under .steadyflow/implementation-patterns/ by default.

Craftsman and Refiner classify the work before editing, then read the relevant pattern files.

| Type | Example | | --- | --- | | Complex component design and implementation | Complex component design and implementation | | Input, form, and validation logic | Inputs, forms, validation rules | | Query, list, detail, and read-only pages | Query pages, list pages, detail pages | | New UI pattern or reusable UI component | New UI patterns or reusable components | | Existing feature change | Modifying an existing feature | | Bug fix | Fixing incorrect behavior | | Data mutation flows | Create, update, delete, submit flows | | State management and derived state | State ownership and derived state | | Integration boundary | API, routing, auth, permission, cache, external modules |

Refactoring Model

| Refactoring type | Standard | | --- | --- | | Implementation pattern unification | Converge different implementations of the same responsibility into the chosen canonical pattern. | | Abstraction | Create a meaningful responsibility boundary, not just a code extraction. | | Component structure change | Reorganize state ownership, component levels, or render structure while preserving behavior. |

Refactoring is judged by whether it makes the code easier to read, predict, and change. Reuse is a consequence of good abstraction, not the main goal.

Review Model

| Rule | Description | | --- | --- | | Checkpoint review | Normal per-step reviews answer whether the step is safe to commit. They focus on blocking bugs, regressions, contracts, failed verification, and critical test gaps. | | Full review | Final Steadywork review, Refactor review, and high-risk changes get comprehensive review including patterns, playbooks, frontend quality, and Refiner candidates. | | Findings first | Issues come before summaries. | | Concrete references | Findings are grounded in real file and line references. | | Risk priority | Bugs, regressions, missing tests, and contract violations come first. | | Toss lens | Frontend code is reviewed through readability, predictability, cohesion, and coupling. | | Playbook extension | User-defined review rules can be accumulated under .steadyflow/review-playbooks/. |

Release Workflow

Steadyflow uses maintainer-only changeset-based releases. This is repository tooling, not a user-facing skill.

| Task | Command | | --- | --- | | Add a changeset | Copy and edit .steadyflow/changesets/_template.md | | Preview release | node scripts/release-steadyflow.js --dry-run | | Apply release | node scripts/release-steadyflow.js | | Tag format | steadyflow-v<version> |

See RELEASE.md for the full release process.

Current Plugin Layout

package.json
bin/
  steadyflow.js
plugins/steadyflow/
  .codex-plugin/plugin.json
  skills/
    steadywork/
    speedwork/
    refactor/
    framer/
  assets/
    subagents/
    templates/
  scripts/
    install-subagents.js
scripts/
  install-steadyflow-subagents.js
  lib/
    skill-installer.js
    subagent-installer.js
  postinstall.js
  release-steadyflow.js