hys-setup

name	hys-setup
description	Sets up an `## Agent skills` block in AGENTS.md/CLAUDE.md and `docs/agents/` so the engineering skills know this repo's issue tracker (local markdown by default), state vocabulary, and domain doc layout. Run before first use of `to-issues`, `to-prd`, `tdd`, `diagnose`, `improve-codebase-architecture`, or `zoom-out` — or if those skills appear to be missing context about the issue tracker, states, or domain docs.
disable-model-invocation	true

Setup (hys-setup)

Scaffold the per-repo configuration that the engineering skills assume:

• Issue tracker — where issues live (local markdown by default; see below)
• State vocabulary — the strings used for the three issue states
• Domain docs — where CONTEXT.md and ADRs live, and the consumer rules for reading them

This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.

Process

1. Explore

Look at the current repo to understand its starting state. Read whatever exists; don't assume:

• AGENTS.md and CLAUDE.md at the repo root — does either exist? Is there already an ## Agent skills section in either?
• CONTEXT.md and CONTEXT-MAP.md at the repo root
• docs/adr/ and any src/*/docs/adr/ directories
• docs/agents/ — does this skill's prior output already exist? If yes, what does issue-tracker.md describe (local markdown, GitHub gh CLI, GitLab glab, other)?
• .scratch/ — sign that the local-markdown issue tracker convention is already in use. If present, sample one issue file: does it have YAML frontmatter (a --- fence with type: issue), or only a bare Status: line? Also check whether .scratch/INDEX.md and any issues/archive/ directories exist.
• Other PRD-like locations: docs/prd/, docs/specs/, requirements/, prds/, specs/
• Other issue-like locations: issues/, tasks/, tickets/

2. Migration check

Classify the repo into one of four cases based on what step 1 found, and announce the case to the user before proceeding:

Case 1 — Clean repo. No .scratch/, no docs/agents/, no existing ## Agent skills block. Skip migration; proceed to step 3.

Case 2 — Already on hys conventions. .scratch/<feat>/issues/*.md files have Status: lines (or frontmatter) that already match the 3-state vocabulary in state-vocabulary.md (ready-for-agent / ready-for-human / done). Tell the user setup will refresh docs/agents/*.md only, leaving issue files untouched. If the issue files still carry only a bare Status: line (no YAML frontmatter), or .scratch/INDEX.md is missing, also run the Case 5 frontmatter migration before proceeding. Otherwise proceed to step 3.

Case 3 — Old setup detected (mattpocock/skills 5-state, or earlier hys 6-state). Either docs/agents/issue-tracker.md references gh / glab CLI, or existing issue files use deprecated states (needs-triage, needs-info, wontfix, inbox, blocked, doing, shelved). Offer:

• (a) Switch to local-markdown + 3-state vocabulary. Rewrite docs/agents/*.md. For each existing issue with a deprecated state, ask the user one-by-one what to do: promote to ready-for-agent / ready-for-human / mark done (if commit already exists) / delete. Do not silently rewrite the Status: line.
• (b) Keep the old GitHub/GitLab tracker. User explicitly chose Other in Section A.

Case 4 — PRD/issue-like files at non-default paths. Surface the paths found. Offer two options, recommending (i) by default since it is non-destructive:

• (i) Configure paths in place. Write the actual paths into docs/agents/issue-tracker.md so the skills read/write there. No file moves.
• (ii) Adopt new layout. Help the user move/symlink existing files into .scratch/<feat>/ structure. Show the planned moves before executing; use git mv where possible.

In all cases, present what was found and the proposed migration plan for the user to confirm before any file is changed. Do not silently rewrite existing user content.

Case 5 — Frontmatter migration (bare Status: lines, no index). Triggered from Case 2 (or runnable on its own) when .scratch/ issues use the legacy bare Status: line instead of YAML frontmatter, or when .scratch/INDEX.md / issues/archive/ are missing. This upgrades the repo to the ARTIFACT-FORMAT.md contract. It is idempotent (skip any file that already has a --- frontmatter fence) and dry-run-first (never touch a file before showing the plan).

Steps:

1. Scan. For every .scratch/<feat>/issues/*.md, classify: already has frontmatter (skip), or bare Status: line (migrate). Note each file's current state string and whether it is done.

2. Build the plan and print it as a single preview, no writes yet:

   📋 Frontmatter 迁移计划（dry-run，未落盘）
   ──────────────────────────────────────────────────────────────
   加 frontmatter（bare Status: → YAML）:
     .scratch/balance/issues/01-init-schema.md   (done)
     .scratch/balance/issues/04-cache.md          (ready-for-agent)
   已有 frontmatter（跳过）:
     .scratch/auth/issues/01-login.md
   移动到 archive/（done issue，git mv 保历史）:
     .scratch/balance/issues/01-init-schema.md → issues/archive/01-init-schema.md
   生成索引:
     .scratch/INDEX.md
     .scratch/balance/SUMMARY.md   (从 done issue 的 ## Comments 完成记录聚合)
   ──────────────────────────────────────────────────────────────
   确认执行？(y / 逐项挑)
   

3. On confirm, execute. For each bare-Status: file, derive the frontmatter fields from the issue schema: type: issue; feature from the directory name; status from the old Status: line; category: enhancement (default — the user can refine later); blocked_by parsed from any existing 前置依赖 section if filenames are referenced, else []; created from git log --diff-filter=A --format=%as -- <file> (fall back to today). Remove the now-redundant bare Status: line. Do not touch the body otherwise (surgical — frontmatter only).

4. Archive done issues with git mv into issues/archive/ so history is preserved and the active working set shrinks. Skip if the user opted out of archiving during migration.

5. Generate .scratch/INDEX.md and each feature's .scratch/<feat>/SUMMARY.md per the format doc.

Report what changed. If refines can't be inferred for a non-top-level issue, leave it unset and note it — the orphan check in /tidy will surface it later.

3. Present findings and ask

Walk the user through the three decisions one at a time — present a section, get the user's answer, then move to the next. Don't dump all three at once.

Assume the user does not know what these terms mean. Each section starts with a short explainer (what it is, why these skills need it, what changes if they pick differently). Then show the choices and the default.

Section A — Issue tracker（issue 追踪位置）.

Explainer: The "issue tracker" is where issues and PRDs live for this repo. to-issues and to-prd read from and write to it.

Default and recommended: local markdown. These skills run fully offline by default, with no network or account dependencies. Pick this unless the user specifically requests otherwise:

• Local markdown（default） — issues live as files under .scratch/<feature>/; pure local, zero external dependencies.
• Other (GitHub / GitLab / Jira / Linear, etc.) — only when the user explicitly asks. Have the user describe the workflow in one paragraph; the skill records it verbatim into docs/agents/issue-tracker.md. Note: this introduces external CLI/account dependencies, conflicting with the local-first goal; the user is responsible for the corresponding environment setup.

Section B — State vocabulary（状态词汇）.

Explainer: Each issue file under .scratch/<feat>/issues/ carries a status: field in its YAML frontmatter. We use a 3-state minimal model tuned for solo dev + agent assistance — no triage, no inbox, no blocked.

The three canonical states:

• ready-for-agent — fully specified, fire-and-forget OK (dispatch to a subagent)
• ready-for-human — fully specified, but needs hands-on judgment / design taste / manual / device testing
• done — completed; immutable (git has the commit; revisions are new issues)

Default: each role's string equals its name. Ask the user if they want to override any.

Section C — Domain docs（领域文档布局）.

Explainer: Some skills (improve-codebase-architecture, diagnose, tdd) read CONTEXT.md for the project's domain language and docs/adr/ for past architectural decisions. They need to know whether the repo is single-context or multi-context (e.g. a monorepo with separate frontend/backend contexts) so they look in the right place.

Confirm the layout:

• Single-context — one CONTEXT.md + docs/adr/ at the repo root. Most repos are this.
• Multi-context — CONTEXT-MAP.md at the root pointing to per-context CONTEXT.md files (typically a monorepo).

4. Confirm and edit

Show the user a draft of:

• The ## Agent skills block to add to whichever of CLAUDE.md / AGENTS.md is being edited (see step 4 for selection rules)
• The contents of docs/agents/issue-tracker.md, docs/agents/state-vocabulary.md, docs/agents/domain.md

Let them edit before writing.

5. Write

Pick the file to edit:

• If CLAUDE.md exists, edit it.
• Else if AGENTS.md exists, edit it.
• If neither exists, ask the user which one to create — don't pick for them.

Never create AGENTS.md when CLAUDE.md already exists (or vice versa) — always edit the one that's already there.

If an ## Agent skills block already exists in the chosen file, update its contents in-place rather than appending a duplicate. Don't overwrite user edits to the surrounding sections.

The session-start orientation convention (load CODEBASE.md/CONTEXT.md, scan ADR titles, check drift) is not written here — it lives once in the global CLAUDE.md template (§6 "Local document layout"), which every session loads. Don't inject a per-repo copy; this block only records the three per-repo choices below. The consumer detail still lives in docs/agents/domain.md.

The block:

## Agent skills

### Issue tracker

[one-line summary of where issues are tracked]. See `docs/agents/issue-tracker.md`.

### State vocabulary

[one-line summary of the three states]. See `docs/agents/state-vocabulary.md`.

### Domain docs

[one-line summary of layout — "single-context" or "multi-context"]. See `docs/agents/domain.md`.

Then write the three docs files using the seed templates in this skill folder as a starting point:

• issue-tracker-local.md — local-markdown issue tracker（默认）
• state-vocabulary.md — the 3-state model
• domain.md — domain doc consumer rules + layout

For a non-default issue tracker (the user explicitly chose "Other"), write docs/agents/issue-tracker.md from scratch using the user's description.

6. Done

Tell the user the setup is complete and which engineering skills will now read from these files. Mention they can edit docs/agents/*.md directly later — re-running this skill is only necessary if they want to switch issue trackers or restart from scratch.