autospec-design
Use when the user wants to adopt a vendor design language for the current repo — fetches the per-vendor DESIGN.md from the berlinguyinca/awesome-design-md catalog, scores the repo against candidate vendors, writes DESIGN.md at the project root, and optionally hands off a migration spec to /autospec-define. Subcommands suggest, apply, and migrate.
- License 许可
- MIT
- 最近更新
- 2026-11-11
- Stars
- ★ 3
- Forks
- 1
01 前言 Front Matter
- name
- autospec-design
- description
- Use when the user wants to adopt a vendor design language for the current repo — fetches the per-vendor DESIGN.md from the berlinguyinca/awesome-design-md catalog, scores the repo against candidate vendors, writes DESIGN.md at the project root, and optionally hands off a migration spec to /autospec-define. Subcommands suggest, apply, and migrate.
02 资源文件 9
- 参考文档codex/prompt.md16.0 KB
- 脚本install.sh10.5 KB
- 参考文档opencode/agent.md16.4 KB
- 参考文档README.md3.2 KB
- 脚本scripts/fetch-design-md.sh7.3 KB
- 脚本scripts/gen-migration-spec.sh3.1 KB
- 脚本scripts/scan-ui-sources.sh2.1 KB
- 脚本scripts/score-suggestion.sh7.3 KB
- 脚本uninstall.sh3.9 KB
03 SKILL.md 正文
autospec-design (harness-neutral)
Skill scaffold for the autospec-design workflow. The full workflow lets the
user pick a vendor design language (Linear, Stripe, Vercel, ...) from a curated
catalog, write DESIGN.md at the project root, and optionally hand off a
migration spec into /autospec-define. The catalog lives at
berlinguyinca/awesome-design-md and is fetched at runtime — never vendored.
This file is the autospec-design trio body. The suggest and apply
subcommands are implemented; migrate still holds a placeholder until issue
#580 lands.
Manage your own context — never exceed 60%. Delegate to subagents whenever your harness supports it.
<!-- autospec-block:startup-self-update SKILL_NAME=autospec-design -->
Self-update mode
If the feature-request argument matches the regex ^\s*update\s*$ (case-insensitive, whitespace-padded), this skill enters self-update mode and does not run the normal pipeline:
- Detect harness by checking which install path exists for this skill:
- Claude Code:
~/.claude/skills/autospec-design/SKILL.md - OpenCode:
~/.config/opencode/agent/autospec-design.md - Codex CLI:
~/.codex/prompts/autospec-design.md
- Claude Code:
- Re-install the full autospec suite from
mainby piping the canonical installer:
Run this one-liner once; it refreshes all autospec skills across all harnesses.curl -fsSL https://raw.githubusercontent.com/berlinguyinca/autospec/main/bootstrap.sh | bash -s -- --skill all --harness all --update - Show the diff between the prior installed file(s) and the freshly fetched copy (e.g.
diff <(cat <prior>) <(curl -fsSL ...SKILL.md)or the equivalent recorded by the installer). - Stop. Do not enter any subcommand. Print the upgrade summary and return to the user.
If no install path is detected, print Self-update: no installed copy of autospec-design found; run install.sh first. and exit.
Invocation
/autospec-design suggest
/autospec-design apply <vendor> [--force] [--branch <name>]
/autospec-design migrate <vendor> [--branch <name>]
suggest— scan the current repo, score every catalog vendor by the framework / domain / brand-language rubric, present the top 3 with a one-line rationale each. Prints only — never modifies any files.apply <vendor>— fetch<vendor>/DESIGN.mdfrom the catalog, write it to<repo-root>/DESIGN.mdon a fresh feature branch (default:feat/design-<vendor>), commit, and push. Refuses to overwrite an existingDESIGN.mdwithout--force. Does not open a PR.migrate <vendor>— generate a migration spec atdocs/specs/<YYYY-MM-DD>-design-migration-<vendor>.mdfrom the scanned UI inventory and hand off to/autospec-define <spec-path>.
The skill exits non-zero if gh auth status fails when issuing a network
operation that needs authentication. See spec
docs/specs/2026-05-26-autospec-design-skill.md for the full contract.
Required capabilities & harness adapter
This workflow assumes a small set of capabilities. Map each one to your harness's actual tool. If a capability is missing, use the listed fallback.
| Capability | Claude Code | OpenCode | Codex CLI | Fallback if missing |
|---|---|---|---|---|
| Read-only codebase research | Agent (subagent_type=Explore) |
task agent in read-only mode |
apply_patch read-only / shell grep |
Do the search in-thread with rg/grep |
| Foreground delegation | Agent (subagent_type=general-purpose) |
nested task agent, await output |
spawn nested CLI session | Do the work in-thread (more context cost) |
| Ask the user a question | AskUserQuestion |
inline prompt | inline prompt | Ask in the response and wait for the next turn |
| Subagent model tier | Tier A: opus + ultrathink; Tier B: sonnet + medium thinking |
Tier A: top task model + high reasoning; Tier B: smaller-tier task + medium reasoning |
Tier A: top GPT + reasoning_effort=high; Tier B: current spark/cost-optimized Codex + reasoning_effort=medium |
Honor the per-phase tier mapping in AGENTS.md; retry the same subagent UP on unavailability |
| <!-- autospec-block:harness-adapter-core --> |
Persistent project notes: write durable preferences to AGENTS.md in the repo root — this is the de-facto standard recognized by Claude Code (also reads CLAUDE.md), OpenCode, and Codex. Per AGENTS.md, subagent dispatches use a two-tier policy: Tier A (top model + extended thinking) for spec work, Tier B (cheaper model + medium thinking) for implementation work. The orchestrator keeps the user's invoked model. Fall back UP the tier on quota/capacity or other unavailability by retrying the same subagent with the stronger tier while preserving parent context.
Harness detection (run once at skill start, before any subcommand)
Detect your harness by checking available tools before any subcommand:
-
Claude Code — the
Agenttool with asubagent_typeparameter is available.TIER_A=opus+ultrathink(the alias, which resolves to the current Claude Opus generation)TIER_B=sonnet(the alias, which resolves to the current Claude Sonnet generation)
-
OpenCode — a
tasktool with model/tier configuration is available (nosubagent_type).TIER_A= top-tier task model + high reasoningTIER_B= smaller-tier task model + medium reasoning
-
Codex CLI — neither
Agentnor a configurabletasktool is available;apply_patchis the primary edit tool.TIER_A= current top GPT model +reasoning_effort=highTIER_B= the spark / cost-optimized variant of the configured model when one exists, else the configured model +reasoning_effort=medium
Fallback rule: If TIER_B is not available in your harness (model unknown, quota/capacity failure, authorization failure, or tool call returns an error for that model), silently retry the same subagent dispatch with TIER_A. Preserve the parent context on retry; for Codex native subagents, fork/inherit the current conversation context and use the latest top GPT model instead of moving the work into the main session. Never ask the user.
Hold TIER_A and TIER_B for the entire skill run. Every "Tier A" and "Tier B" reference below resolves to these harness-specific values.
Catalog source (single source of truth)
Fetched at runtime, never vendored:
AUTOSPEC_DESIGN_CATALOG_OWNER="${AUTOSPEC_DESIGN_CATALOG_OWNER:-berlinguyinca}"
AUTOSPEC_DESIGN_CATALOG_REPO="${AUTOSPEC_DESIGN_CATALOG_REPO:-awesome-design-md}"
AUTOSPEC_DESIGN_CATALOG_REF="${AUTOSPEC_DESIGN_CATALOG_REF:-main}"
Per-vendor DESIGN.md is fetched via gh api repos/${owner}/${repo}/contents/design-md/${vendor}/DESIGN.md?ref=${ref} --jq '.content' | base64 -d, with a fallback to curl -fsSL https://raw.githubusercontent.com/.... Cache lands under ~/.autospec/design-cache/<vendor>/DESIGN.md with a 24h freshness window. The catalog fetcher script lands in issue #576 (fetch-design-md.sh).
Suggest
Model tier:
TIER_B(implementation work) — scoring is mechanical; the rubric is a fixed table and the helper is deterministic.
suggest scans the current repo, scores every catalog vendor against a fixed
rubric, and presents the top 3 candidates with a one-line rationale each. It is
read-only — it never modifies any file in the target repo.
Run the deterministic scorer (it prints tab-separated <score>\t<vendor>\t<rationale>
lines, highest score first):
bash skills/autospec-design/scripts/score-suggestion.sh <repo-root>
The scorer:
- Fetches the catalog vendor list once (via
gh api .../contents/design-md,curlfallback). When you have already fetched it, pass it in viaAUTOSPEC_DESIGN_VENDORSto avoid a second round-trip. - Detects repo signals: framework (
package.json,next.config.*,vite.config.*,angular.json,svelte.config.*, Tailwind config), brand keywords (README +package.jsonname/description), and product-domain keywords (README). - Scores each vendor on the rubric below (cap 6):
- Framework match (+2) — repo uses a web/JS UI framework AND the vendor is a developer / SaaS / web-product brand (e.g. Linear, Vercel, Stripe).
- Brand match (+1) — the vendor's normalized name appears in the repo's
README or
package.json. - Domain match (+1) — a vendor-name token overlaps the repo README.
Present the top 3 to the user with their rationales and let them pick. Then run
/autospec-design apply <vendor> with the chosen vendor. Do not apply
automatically — suggest only recommends.
Apply
Model tier:
TIER_B(implementation work) — write-out is a deterministic branch-and-commit; no novel design.
apply <vendor> [--force] [--branch <name>] fetches <vendor>/DESIGN.md from
the catalog and writes it to <repo-root>/DESIGN.md on a fresh feature branch,
commits, and pushes. It is mechanical — no subagent dispatch. The flow:
- Parse
<vendor>plus optional--forceand--branch <name>. - Validate
<vendor>exists in the catalog by delegating tofetch-design-md.sh(its exit code is the validation — a missing vendor exits non-zero and prints Levenshtein hints; do not duplicate that logic). - If
DESIGN.mdalready exists at the repo root and--forceis absent: refuse, print agit diffhint, and exit non-zero. Never silently overwrite. - Refuse to commit on
main— when--branchis absent, auto-createfeat/design-<vendor>; otherwise use the supplied branch name. - Fetch the DESIGN.md body (cache hit or network) via
fetch-design-md.sh. - Write the body to
<repo-root>/DESIGN.md. git add DESIGN.md, commit withfeat(design): adopt <vendor> design language, and push the branch (git push -u origin <branch>).- Print a status summary: branch name, DESIGN.md byte count, and the
next-step hint (
open a PR, or run /autospec-design migrate <vendor>).
apply never opens a PR — the operator does that, or /autospec-design migrate takes over. It is idempotent: a second run on the same branch with the
same vendor rewrites identical bytes and exits without creating a duplicate
commit.
The deterministic flow below is the canonical script for the steps above. Run
it verbatim (it reads <vendor> from the invocation; the DESIGN_* overrides
exist only so the test harness can point it at a fixture repo and a seeded
cache). It honors --force/--branch via the DESIGN_FORCE/DESIGN_BRANCH
mappings the wrapper sets from the parsed flags.
# autospec-design-apply-flow
set -u
vendor="${DESIGN_VENDOR:?vendor required: /autospec-design apply <vendor>}"
repo_root="${DESIGN_REPO_ROOT:-$(git rev-parse --show-toplevel)}"
fetch="${DESIGN_FETCH:-skills/autospec-design/scripts/fetch-design-md.sh}"
branch="${DESIGN_BRANCH:-feat/design-$vendor}"
target="$repo_root/DESIGN.md"
# Guard: refuse overwrite without --force.
if [ -e "$target" ] && [ "${DESIGN_FORCE:-0}" != "1" ]; then
printf 'autospec-design apply: %s already exists. Re-run with --force to overwrite (inspect with: git -C %q diff -- DESIGN.md).\n' \
"$target" "$repo_root" >&2
exit 1
fi
# Validate vendor + fetch body (non-zero here = unknown vendor or network).
body="$(bash "$fetch" "$vendor")" || exit $?
# Never commit on main: create/switch to the feature branch.
git -C "$repo_root" checkout -B "$branch" >/dev/null 2>&1 || {
printf 'autospec-design apply: could not create branch %s\n' "$branch" >&2
exit 1
}
# Write, stage, commit.
printf '%s' "$body" > "$target"
git -C "$repo_root" add DESIGN.md
if git -C "$repo_root" diff --cached --quiet -- DESIGN.md; then
printf 'autospec-design apply: DESIGN.md already matches %s on branch %s.\n' \
"$vendor" "$branch"
else
git -C "$repo_root" commit -q -m "feat(design): adopt $vendor design language"
fi
# Push unless the test harness suppresses it.
if [ "${DESIGN_NO_PUSH:-0}" != "1" ]; then
git -C "$repo_root" push -u origin "$branch"
fi
bytes="$(wc -c < "$target" | tr -d ' ')"
printf 'autospec-design apply: wrote %s (%s bytes) on branch %s.\n' \
"$target" "$bytes" "$branch"
printf 'Next: open a PR, or run /autospec-design migrate %s.\n' "$vendor"
Migrate
Model tier:
TIER_B(implementation work) — emits a structured spec and hands off to/autospec-define.
migrate <vendor> [--branch <name>] turns an applied vendor DESIGN.md into a
tracked migration spec and then hands that spec to /autospec-define for normal
autospec issue decomposition. It assumes /autospec-design apply <vendor> has
already written the repo-root DESIGN.md.
Preconditions and flow:
- Verify
<repo-root>/DESIGN.mdexists and its first heading or first 20 lines mention<vendor>(case-insensitive, with suffixes like.appignored). Otherwise printRun /autospec-design apply <vendor> first.and exit non-zero. - Run
scan-ui-sources.sh <repo-root>; if no UI files are found, surface the helper's no-UI-files message and exit non-zero. - Run
gen-migration-spec.sh <vendor> <repo-root>to writedocs/specs/<YYYY-MM-DD>-design-migration-<vendor>.md. - Commit the spec on the current feature branch (or create/switch to
--branch <name>first when provided). - Hand off to
/autospec-define <spec-path>. If that handoff fails, do not swallow the error: leave the committed spec on disk and report the exact command for manual recovery.
The deterministic flow below is the canonical shell portion for steps 1-4. The
actual harness handoff is the final printed /autospec-define <spec-path> line;
invoke that skill through the harness after this script succeeds.
# autospec-design-migrate-flow
set -u
vendor="${DESIGN_VENDOR:?vendor required: /autospec-design migrate <vendor>}"
repo_root="${DESIGN_REPO_ROOT:-$(git rev-parse --show-toplevel)}"
branch="${DESIGN_BRANCH:-}"
scan="${DESIGN_SCAN:-skills/autospec-design/scripts/scan-ui-sources.sh}"
generate="${DESIGN_GENERATE:-skills/autospec-design/scripts/gen-migration-spec.sh}"
target="$repo_root/DESIGN.md"
vendor_key="$(printf '%s' "$vendor" | sed -E 's/[.](app|ai|com|io)$//' | tr '[:upper:]' '[:lower:]')"
if [ ! -f "$target" ] || ! head -20 "$target" | tr '[:upper:]' '[:lower:]' | grep -qF "$vendor_key"; then
printf 'Run /autospec-design apply %s first.\n' "$vendor" >&2
exit 1
fi
if [ -n "$branch" ]; then
git -C "$repo_root" checkout -B "$branch" >/dev/null 2>&1 || {
printf 'autospec-design migrate: could not create branch %s\n' "$branch" >&2
exit 1
}
fi
# Prove the UI inventory is non-empty before generating the spec.
inventory="$(bash "$scan" "$repo_root")" || exit $?
if printf '%s' "$inventory" | grep -q '"files":\[\]'; then
printf 'gen-migration-spec: no UI files found in %s; nothing to migrate.\n' "$repo_root" >&2
exit 2
fi
spec_path="$(bash "$generate" "$vendor" "$repo_root")" || exit $?
git -C "$repo_root" add "$spec_path"
if git -C "$repo_root" diff --cached --quiet -- "$spec_path"; then
printf 'autospec-design migrate: migration spec already committed: %s\n' "$spec_path"
else
git -C "$repo_root" commit -q -m "docs(design): add $vendor migration spec"
fi
printf 'autospec-design migrate: wrote %s.\n' "$spec_path"
printf '/autospec-define %s\n' "$spec_path"
Hard rules
- Never overwrite an existing
DESIGN.mdwithout--force. - Never open a PR automatically — the operator opens it (or
/autospec-definetakes over via the migration spec). - Never modify the issue title (when running via the autospec pipeline).
- Always idempotent — running
applytwice with the same vendor on the same branch is a no-op after the first commit. ghCLI only for GitHub ops;curlonly as a fallback for catalog reads.
04 同仓库更多 Skills
trio-pass-skill
暂无简介
duo-pass-skill
暂无简介
duo-divergence-skill
暂无简介
autospec
Use when the user wants to ship a feature end-to-end across multiple commits — bootstraps repo if missing, brainstorms a design spec, decomposes into linked GitHub issues, or splits an existing spec into issues, then runs an autonomous implementation loop with auto-merge.
autospec-upgrade
Use when the user wants to upgrade an Angular, Next.js, or React project to the latest official versions safely — by locking observable behavior before touching versions, upgrading one major at a time with official codemods, and gating completion on mutation score rather than coverage theater.
autospec-ui-audit
Use when a React Router application needs a deterministic whole-site route inventory before UI, UX, navigation, or evidence auditing begins.