workflow
Routes any dev task into the right execution tier (Small/Medium/Large) and carries condux's operating rules — proportional effort, lazy skill loading, soft gates, implement-yourself-by-default.
- License 许可
- MIT
- 最近更新
- 2026-11-03
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- workflow
- description
- Routes any dev task into the right execution tier (Small/Medium/Large) and carries condux's operating rules — proportional effort, lazy skill loading, soft gates, implement-yourself-by-default.
- when_to_use
- Trigger with any dev task, however small or mundane — feature, bug fix, refactor, new endpoint, UI change, adding tests, CI and tooling config, docs and README edits, a one-line tweak. Every task starts here regardless of size (the tier decides the ceremony), including requests to start or prep a task, like loading its spec before beginning. Other skills execute within /workflow, not instead of it. Also the operating manual — how condux works: tiers, soft gates, checkpoints, named agents.
- argument-hint
- <task description>
02 资源文件 31
- 参考文档evals/trigger_eval.json3.0 KB
- 参考文档hooks/codex-hooks.json672 B
- 参考文档hooks/hooks.json389 B
- 脚本hooks/mod/board/badges.ts910 B
- 其他hooks/mod/board/board.tsx26.2 KB
- 脚本hooks/mod/board/graph.ts6.6 KB
- 脚本hooks/mod/board/parse-ledger.ts1.7 KB
- 脚本hooks/mod/board/parse-plan.ts4.3 KB
- 脚本hooks/mod/board/state.ts5.9 KB
- 脚本hooks/mod/board/stepper.ts1.4 KB
- 脚本hooks/mod/board/text.ts7.1 KB
- 脚本hooks/mod/kit/charts.ts6.1 KB
- 脚本hooks/mod/kit/locate.ts881 B
- 脚本hooks/mod/kit/paths.ts1.6 KB
- 其他hooks/mod/register.tsx935 B
- 其他hooks/mod/tests/autoopen.test.tsx2.8 KB
- 其他hooks/mod/tests/board.test.tsx7.6 KB
- 其他hooks/mod/tests/capped.test.tsx2.9 KB
- 其他hooks/mod/tests/chrome-pane.test.tsx5.8 KB
- 其他hooks/mod/tests/chrome.test.tsx5.6 KB
- 脚本hooks/mod/tests/fixtures.ts5.0 KB
- 其他hooks/mod/tests/harness.tsx5.5 KB
- 其他hooks/mod/tests/parse-ledger.test.tsx3.3 KB
- 其他hooks/mod/tests/parse-plan.test.tsx3.8 KB
- 其他hooks/mod/tests/register.test.tsx597 B
- 其他hooks/mod/tests/state.test.tsx9.3 KB
- 其他hooks/mod/tests/status.test.tsx4.1 KB
- 其他hooks/mod/tests/text.test.tsx2.7 KB
- 脚本hooks/mod/types/index.d.ts4.4 KB
- 参考文档hooks/routing.md1.6 KB
- 脚本hooks/session-start.mjs2.2 KB
03 SKILL.md 正文
/workflow
Pick the right tier, confirm it, execute. No over-engineering for a button change. No under-planning for a cross-cutting feature.
Usage
/workflow $ARGUMENTS
Live Context
git status --short 2>/dev/null || echo "(not a git repository yet)"
git log --oneline -5 2>/dev/null || echo "(no commits yet)"
Operating Rules
Condux is lean and proportional — the opposite of "always run every gate."
- Proportional, not maximal. Match the tier to the task. Don't discovery a typo. Don't wing a cross-cutting refactor.
- Lazy loading. Never load
discovery,draft-plan,test-first-development,subagent-execution, orfinalizeupfront. Load a skill only when the tier flow reaches the step that needs it. - Soft gates, not hard walls. A gate (e.g. discovery before planning) can be skipped — but only consciously. If a gate hasn't run, ask the user whether they want to skip it; never silently bypass it.
- The user is in control. Condux shapes how you work, but explicit user instructions (CLAUDE.md, AGENTS.md, direct requests) always win. "Treat this as LARGE" or "skip the plan" is always valid.
- Implement yourself by default. Spawning agents is the exception — only delegate with a concrete justification (see Agents below).
- House style rides along. Before the first line of code in any tier, load
the
coding-directiveskill if it is installed — skip silently when it isn't. Codebase mimicry and repo config still win over the directive. - Two tracks, one of them triggered. Tactical is the task in front of you.
Strategic is the environment that produced it — would a narrower type, a
lint rule, or a written convention have made this task's bug impossible?
The strategic track is not a standing obligation; that would violate rule
- It fires on a trigger, and the triggers are in Environment Hardening.
Entry Contract
Every dev task starts with /workflow — no exceptions unless the user says so.
Valid bypasses (explicit user instruction required):
- Mid-flow: "I've already designed/planned this" → skip to the relevant step.
- Explicit opt-out: "skip workflow", "just do it" → proceed, but note the skip.
Not valid bypasses:
- Your own judgment that the task "seems small" — tier inference is this skill's job, not yours.
- Being loaded as companion context alongside another skill — run
/workflowfirst; the other skill executes within it, not instead of it.
Tiers
| Tier | Looks like | Flow |
|---|---|---|
| SMALL | isolated change, 1–3 files, clear requirements (a button, a label, a prop, a typo) | implement → /preflight → /finalize |
| MEDIUM | multi-file, some design needed, known boundaries (new form + API route, new procedure) | quick inline plan → implement → /preflight → /finalize |
| LARGE | cross-cutting, unclear scope, multiple subsystems (new module, auth flow, data-model change) | /discovery → /draft-plan → implement → /preflight → /finalize |
Every tier ends with preflight then finalize — no exceptions.
The Router
- Infer the tier. How many files? Requirement clear or needs design? Crosses service/package boundaries? Unknowns needing exploration first? In a mobile app, also: does it touch the native layer (finalize's native-change check lists what does)? That doesn't change the tier — a one-line Kotlin fix is still SMALL — but say so when confirming, because nothing can verify it until the app is rebuilt and reinstalled.
- Spec lookup. Detect the package root (walk up from CWD to git root, find the
nearest
package.json/Cargo.toml/go.mod/pyproject.toml). Check both scopes (deduplicate if identical):ls <package-root>/specs/ 2>/dev/nullandls <git-root>/specs/ 2>/dev/null. Match the task subject to a spec dir (fuzzy kebab-case: "checkout flow" →specs/checkout-flow). If found, readindex.md, then load by task type — bug/debug →quirks.md,api.md,fields.md; refactor →implementation.md,decisions.md; new feature →prd.md,decisions.md,api.md,fields.md(any of these the spec does not have is skipped silently). Carry this context through; don't re-read mid-task. No spec → proceed without comment. - Confirm with the user. State the inferred tier + a one-sentence reason. If a
spec was loaded, mention it and offer the companion: "Found spec for
checkout-flow— loaded as context. Want the live HTML preview while we work? [y/n]" (if yes, loadtechnical-specand run its preview). Wait for explicit confirmation before proceeding. - Execute the tier flow, loading only the skills the tier needs, when needed.
- Checkpoints (MEDIUM/LARGE). At each phase boundary, stop and present a "what next?" menu (AskUserQuestion), recommended option first. The user drives every transition — never auto-advance. SMALL runs linear with no menus.
Tier flows
- SMALL: implement directly (no plan doc, no discovery) →
/preflight→/finalize. - MEDIUM: short inline plan (same section shape as draft-plan, kept lean —
Overview · Files · Interfaces · Sketch where non-obvious · Edge cases) → CP-1 →
implement top-to-bottom → CP-2 →
/preflight→/finalize→ CP-3. - LARGE: load
discovery, run fully to sign-off → loaddraft-plan, produce the plan doc, sign-off → CP-1 → implement task by task, keeping the Progress Ledger (subagent-executionif the user picks it) → CP-2 →/preflight→/finalize→ CP-3.
Checkpoints
After the user picks, load only that skill, run it, then return to the nearest checkpoint and re-present the menu until the user chooses Done.
When the question tool caps the options. CP-1 and CP-3 have five rows, and some hosts' question tools take four (Claude Code's AskUserQuestion does). The first four rows go on buttons, recommended first. The fifth row rides in the free-text slot the tool adds ("Other"), and the question text names it: "Plan ready — how do we proceed? (or type 'revise' to rework the plan)" for CP-1, "(or say done)" for CP-3. Never merge two rows into one button to make room — "Use agents" for the two agent rows is exactly the erosion this rule prevents. A host with no cap, or a plain-text menu, shows every row.
When the question tool doesn't block. Codex's request_user_input queues
the question beside the turn: the model keeps working, the host may answer it
on a timer (autoResolutionMs), and an unanswered question is dropped when the
turn ends. Every checkpoint therefore ends the turn with the full menu as a
numbered plain-text list in the final message (the user replies with a number
or a row name). The picker may be shown as well, but the final message is the
menu of record. Never treat a picker answer you didn't see the user give as
their choice.
CP-1 — Plan ready
After draft-plan sign-off (LARGE) or the inline plan (MEDIUM). Plan review already happened (or was declined) in draft-plan's own save step — don't re-offer it.
| Option | What it does |
|---|---|
| Start implementing (recommended) | Implement the plan top-to-bottom yourself |
| Write tests first | Load test-first-development; one upfront consent, then test-first |
| Spawn specialist agents | Load subagent-execution; execute the plan with named agents |
| Dispatch independent tasks in parallel | Load subagent-deployment; fan out N independent tasks |
| Revise the plan | Loop back to draft-plan with the new direction |
The menu is the full menu. Present every row above, every time — including both subagent options. Implement-yourself-by-default governs the recommendation marker, never which options appear: the user decides whether agents pay off, and an option they never see is a decision made for them. If plan sign-off and CP-1 get combined into one prompt (common in plan-approval UIs), the combined menu must still carry the full CP-1 option set.
CP-2 — Implementation done
| Option | What it does |
|---|---|
| Verify & finalize (recommended) | Run preflight, then finalize |
| Code review first | Load code-review on the diff before finalizing |
| Keep building | More scope remains — re-confirm the tier if it grew |
CP-3 — Finalized and green
| Option | What it does |
|---|---|
| Verify it live (recommended when the change has a runnable surface — an app on an emulator counts) | Load the live-verification skill and follow it — including on a mobile app: drive the real UI, endpoint or emulator, check each claim against observed behaviour, and write its report |
| Code review (recommended) | /code-review the diff before merging |
| Commit | Load the git-commit skill if installed (conventional message from the diff, safe staging); otherwise follow the repo's commit conventions |
| Cut a release | Load the release skill if installed — machinery detection, dry-run plan, then tag → push → GitHub release; otherwise follow the repo's release conventions |
| Done | Stop here |
Skills and Gates
Load each only when its step is reached.
| Skill | When | Gate discipline |
|---|---|---|
discovery |
LARGE, before planning, or scope unclear | soft gate — ask before skipping |
blueprint |
discovery's propose step, or a standalone mockup/visualization ask | load only when a UI surface or data model is in play; structure, never styling |
draft-plan |
LARGE, after discovery sign-off | needs a signed-off design; no design → apply the discovery soft gate first |
test-first-development |
user asks, or picks it at CP-1 | one upfront consent; always ask before editing an existing test spec |
subagent-execution |
LARGE plan where specialization/parallelism pays off | default is implement yourself; keeps the Progress Ledger |
subagent-deployment |
2+ independent tasks, no shared files/deps | ad-hoc work, not ordered plans |
preflight |
end of every tier, before finalize | automatic on SMALL; recommended CP-2 choice |
finalize |
after all implementation | runs in order, once, stops on first failure; check AGENTS.md for the real commands |
live-verification |
after finalize, when the change has a runnable surface | offer at CP-3; one pass, no loop; skipping is fine, silent skipping is not |
code-review |
on request only | never auto-triggers, never fixes; after finalize you may ask ONCE |
root-cause-analysis |
any bug investigation | load when debugging starts, not proactively; investigation before fixes |
plan-review |
plan/spec annotation in the browser | via ExitPlanMode/Stop hook, draft-plan's save step, or manually |
technical-spec |
spec context + persistence (see below) | confirm before writing; never silently modify spec files |
Spec companion (technical-spec): the router's step-2 lookup loads spec context
silently — no spec, no noise. discovery integrates it at sign-off (design doc always;
structured spec default-on, opt-out + live preview). preflight closes the loop — its
Drift Check compares the implementation against the task's spec before finalize.
Whenever a task modifies spec files
(specs/, OpenAPI YAMLs, contracts, field mappings), offer: "Want the live spec
preview open to review the changes?"
Artifacts
Two tiers, split by durability — not by which skill produced them.
| Tier | Where | Contents | Git |
|---|---|---|---|
| Durable | <git-root>/specs/ |
tech specs (technical-spec), browsable via spec-browser |
committed |
| Working state | <git-root>/.condux/ |
designs/ · plans/ · progress/ · scratch/ · verification/ (live-verification evidence) |
gitignored |
The spec is what you keep; the design and plan are scaffolding for building
it. Don't promote working state into docs/ or the repo root — a project's
docs/ belongs to the project, not to condux.
Citation direction: durable content may not depend on ephemeral content.
A committed file may not cite a path inside .condux/ — that path is gone on
any other machine and on any fresh clone, so the reference is dead for everyone
but its author. When a spec, a changelog entry or a backlog item needs to point
at a design or a verification report, promote it first: copy that file into
the durable tree (the spec directory it belongs to) and cite the committed
path. If the artifact no longer exists, say so and name what survives — a PR, a
commit — rather than a path that resolves nowhere. The split above says where
each artifact lives; this says which direction a reference may point.
Bootstrap. .condux/ is created on demand at the git root by the first
skill that writes there. Before that first write, check it's ignored:
git check-ignore -q .condux/ || echo "not ignored"
If it isn't, offer once: "condux keeps its working files in .condux/ — add
it to .gitignore so they stay out of your commits?" On yes, append
.condux/ to the repo's .gitignore. If the user would rather not touch a
tracked file, write it to .git/info/exclude instead. Never edit either file
without asking. Not a git repo → fall back to CWD and say so once.
Override. A project can relocate either tier in AGENTS.md; an explicit
override always wins over these defaults.
Progress Ledger
Conversation memory does not survive compaction, and a plan file records intent,
not progress. Whoever implements a plan saved in .condux/plans/ — you inline,
or subagent-execution — keeps one ledger beside it,
.condux/progress/<feature-slug>.md (the plan's file name minus its date and
extension):
# Progress: <feature-slug>
Plan: .condux/plans/<plan-file>.md
BASE: <sha7 of HEAD before Task 1>
- [x] Task 1: <name> — commit <sha7>
- [x] preflight clean
- [x] committed <sha7>; PR #N open
- Task lines are appended after the task's commit, one per task, in the same message as ticking the todo. A line names a real commit.
- Wrap-up lines (no task number) are appended as each checkpoint step
finishes:
code-review,preflight,finalize, live verification, then the commit or PR line. A tool that reads the ledger — the/conduxboard — turns them into the pipeline's done and still-to-come steps. - Start of work: if a ledger exists, tasks ticked there are DONE; resume at the first one that is not.
- No saved plan file, no ledger. A SMALL task and a MEDIUM inline plan have nothing for a ledger to key on; do not invent a plan file to get one.
- The ledger is a recovery aid, not the source of truth: the commits it names
exist in git even when context no longer remembers them.
.condux/is gitignored working state (see Artifacts), so never cite a ledger from a committed file.
Agents
Five named specialist agents ship with condux — never invent a generic subagent
with an injected prompt. (Another installed skill that mandates its own spawn type
and ships the worker's contract, like deep-research, runs as written — see
subagent-execution.) Implement yourself by default; spawn only with concrete
justification (unfamiliar codebase, external API to verify, genuinely parallel
exploration, or a LARGE plan via subagent-execution).
explorer— read-only codebase navigation (sonnet at low effort, non-blocking; LSP over grep).researcher— external API/library verification (opus, non-blocking; resolves the installed version first, omits what it can't verify).planner— design → executable plan (sonnet; always delegates to explorer, and researcher when external libs are involved, before planning).coder— executes a provided plan only (sonnet; no exploration, no typecheck/lint/test — that's finalize's job).scout— one angle of a survey, dispatched only by/condux:research(sonnet; writes only its own notes file).
Pipeline: explorer/researcher gather (non-blocking) → planner plans → coder executes
→ finalize validates. Spawn mechanics, model tiering, and the parallel-safety
checklist live in subagent-execution and subagent-deployment.
Escalating Mid-Task
Scope turns out bigger than the confirmed tier? Stop immediately, report what you found ("this touches auth middleware, not just the UI"), re-confirm the tier before continuing. Never silently expand scope.
Environment Hardening
The strategic track, fired by a trigger rather than run on every task. Two triggers, both observed rather than imagined:
- Repeated friction. The same obstacle cost time twice — twice in this task, or once here and once earlier in the session.
- A workaround taken. You bypassed a convention, widened a type, disabled a
rule, or special-cased around a design to make the change land.
preflight's no-workarounds box catches the ones you stopped noticing.
When one fires, spend a sentence on the cause rather than the symptom. Agents succeed in a pit of success — an environment where the wrong thing is hard to express:
| Lever | Looks like |
|---|---|
| Constrained surface | a narrower type, a smaller public API, an argument that cannot be passed wrong |
| Rules that force correctness | a lint rule, a stricter compiler flag, a test that fails on the shape and not just the value |
| Written convention | a line in AGENTS.md / CLAUDE.md or the house-style skill, so a reviewer cites it instead of re-deriving it |
| Data the agent lacks | dev-server or production logs, a test database, browser access to watch the thing actually render |
The output is a sentence to the user, or a backlog item — never a new
artifact. Name the hardening and let the user decide. If a backlog skill
(record, or the repo's own convention) is installed and they want it kept,
file it there. Do not create a file for it, do not add a .condux/ directory
for it, and do not implement it inside the current task — that is scope
expansion, which Escalating Mid-Task already forbids.
Silence is the correct output when neither trigger fired. A clean SMALL task gets no hardening commentary at all.
Red Flags
Stop if you catch yourself doing any of these:
| Doing | Instead |
|---|---|
Skipping /workflow because the task "seems small" |
That judgment belongs to the router — run it first |
| Loading every condux skill upfront | Let the tier flow pull each in at its step |
| Discovery or a plan doc for a SMALL/MEDIUM task | Implement directly; verify; finalize |
| Tests / lint / typecheck mid-implementation | Save it all for finalize |
| Spawning agents for a task you can just do | Default is to implement yourself |
| Omitting the subagent options from a checkpoint menu | The default shapes the recommendation, never the menu — present every CP-1 row |
| Merging or dropping rows to fit a four-option question tool | Four rows on buttons, the fifth named in the question text and taken through "Other" |
| Silently skipping discovery on a LARGE task | Ask — it's a soft gate, not a free pass |
| Rewriting a test spec to make it pass | Stop and ask — never silently edit specs |
| Auto-running code-review, commits, or agents | They're checkpoint choices; run only when picked |
Verifying live without loading live-verification |
Load it — its report.md is the evidence (9 of 11 ad-hoc runs in a mobile eval left none) |
| Auto-advancing past a checkpoint on MEDIUM/LARGE | The user owns every transition |
| A checkpoint asked only through a non-blocking picker (Codex) | End the turn with the numbered menu in plain text — the picker disappears when the turn ends |
| Absorbing a workaround silently so the change lands | Name it — that's a hardening trigger, and preflight asks for it anyway |
| Expanding scope past the confirmed tier | Stop, report, re-confirm |
Tips
- Be specific: "add export button to invoice table that calls exportInvoices" → SMALL. "improve the invoice flow" → clarify before a tier can be inferred.
- Override anytime: "treat this as LARGE" is always valid.
- Tests-first is opt-in: pick it at CP-1 or say so anytime.
- Review is separate: after
/finalize, run/code-reviewif you want one.
04 同仓库更多 Skills
orphan
暂无简介
no-blurb
暂无简介
usage-trace
Checks and manages durable, local usage capture — ingest, health status, and the opt-in limit snapshot — for Claude Code and Codex. Capture itself runs automatically at session start.
toolkit-skill-standards
Use when writing or reviewing a SKILL.md for jabworks/agentic-toolkit — frontmatter budgets, the trigger contract ("Use when…" description or when_to_use field), progressive disclosure into references/, and keeping a new description out of existing skills' trigger space. Triggers include "review this skill description", "write the frontmatter", "does this collide with an existing skill", "where should this content live". Not for scaffold/sync mechanics; use toolkit-foundry.
toolkit-research-frontier
Use when planning improvement work on jabworks/agentic-toolkit itself — open problems (trigger-collision automation, YAML-strict frontmatter checks, docs-catalog enforcement), existing assets, the next three concrete steps, and the four-front library-health campaign with commands and success criteria. Triggers include "let's improve our toolkit", "let's improve this repo", "what should we improve next", "toolkit roadmap", "open problems", "run the health campaign".
toolkit-plugin-reference
Use when writing or editing plugin.json, marketplace.json, or package manifests in jabworks/agentic-toolkit and the exact schema matters — required fields, the .claude-plugin/.codex-plugin pairing and where it diverges (interface, hooks), the skills-path form, how the four install channels consume the repo, and which SKILL.md frontmatter fields are real. Triggers include "what fields does plugin.json need", "claude vs codex manifest", "marketplace entry format", "how opencode loads skills".