AGENT SKILL

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

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."

  1. Proportional, not maximal. Match the tier to the task. Don't discovery a typo. Don't wing a cross-cutting refactor.
  2. Lazy loading. Never load discovery, draft-plan, test-first-development, subagent-execution, or finalize upfront. Load a skill only when the tier flow reaches the step that needs it.
  3. 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.
  4. 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.
  5. Implement yourself by default. Spawning agents is the exception — only delegate with a concrete justification (see Agents below).
  6. House style rides along. Before the first line of code in any tier, load the coding-directive skill if it is installed — skip silently when it isn't. Codebase mimicry and repo config still win over the directive.
  7. 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
    1. 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 /workflow first; 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

  1. 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.
  2. 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/null and ls <git-root>/specs/ 2>/dev/null. Match the task subject to a spec dir (fuzzy kebab-case: "checkout flow" → specs/checkout-flow). If found, read index.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.
  3. 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, load technical-spec and run its preview). Wait for explicit confirmation before proceeding.
  4. Execute the tier flow, loading only the skills the tier needs, when needed.
  5. 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 → load draft-plan, produce the plan doc, sign-off → CP-1 → implement task by task, keeping the Progress Ledger (subagent-execution if 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 /condux board — 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

  1. Be specific: "add export button to invoice table that calls exportInvoices" → SMALL. "improve the invoice flow" → clarify before a tier can be inferred.
  2. Override anytime: "treat this as LARGE" is always valid.
  3. Tests-first is opt-in: pick it at CP-1 or say so anytime.
  4. Review is separate: after /finalize, run /code-review if you want one.

04 同仓库更多 Skills

jabworks
jabworks/agentic-toolkit

orphan

暂无简介

★ 2
jabworks
jabworks/agentic-toolkit

no-blurb

暂无简介

★ 2
jabworks
jabworks/agentic-toolkit

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.

★ 2
jabworks
jabworks/agentic-toolkit

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.

★ 2
jabworks
jabworks/agentic-toolkit

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".

★ 2
jabworks
jabworks/agentic-toolkit

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".

★ 2