メニュー
Bootstraps the project-harness bundle by establishing its five skills, running a four-step idempotent setup on first use per repo, and routing project-state edits through the right sibling skill.
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
Build an interactive "codesign" decision page as one self-contained HTML file: the reader toggles choices (pick-one or pick-any), adds notes, and exports the decision as Markdown and JSON with stable IDs (sec-01, ch-01-a) so picks can be quoted in chat — "keep ch-01-a, swap ch-02-b" yields a diffable v2. Use when the user wants to choose between options and capture the decision: design directions, plan A vs B, prioritization, async option pages for a stakeholder. Triggers: codesign, co-design, decision page, pick from these, which should we, compare the options, prioritize these. ALWAYS confirms before generating — lists the UNANSWERED questions found in recent context, each with its ID and a recommendation, then waits for a yes; the gate fires even on explicit invocation with an argument. Answered questions are out of scope; if context is mostly settled material it offers html-explain instead. Styled by use-html-theme. NOT for signing macOS/iOS binaries (Apple's codesign).
Build a read-only "explainer" page as one self-contained HTML file — a rich explanation of settled material, where diagrams, annotated figures, charts, and small interactive widgets do work prose cannot. Authoring maps which parts are intrinsically hardest, budgets the page around them, then enriches ONLY where comprehension actually breaks. Use when an explanation should be a shareable PAGE not inline chat: "explain the design we just landed", "write up what the tests showed", "make an explainer for this spec", "deep dive on X as a page", explainer, walkthrough page, "explain this visually". Reads recent context and ALWAYS confirms the target before generating, even on explicit invocation with an argument. If context is mostly UNANSWERED questions it offers html-codesign instead (that answers questions; this explains — including a deep dive on one already resolved). Inline chat explanations are the `explain` skill; charts defer to dataviz when present. Pairs with use-html-theme.
Explain anything in a concrete-anchored style — succinct, just-enough context, always grounded in a real example. Use when the user invokes /explain, or asks in their own words: "explain X", "give me a before and after", "add more context on <finding/step/option>", "show examples of the options so I can decide", "what does this change get us", "what's the bigger picture here", "give me step by step instructions". A bare "explain" right after an explanation means "not enough to act on yet": diagnose the gap (bigger picture, clearer language, or a sharper example) and usually rewrite, not append; an argument steers the focus; a dissimilar target restarts fresh. Modes (inferred from the target; explicit argument wins): default, options (example per option + recommendation), deeper, steps (operator instructions). Not for manual testing steps (manual-test-guide) or whole-session recaps.
Whenever the user asks Claude to generate or restyle HTML — a page, artifact, mockup, dashboard, doc, status page, landing page, release-notes page, HTML email, or styled snippet — offer a small catalog of visual themes and apply the chosen one to all subsequent HTML in the session. v1 catalog: birchline (warm editorial), technical-minimal (docs-site neutral), high-contrast-dark (dashboard/terminal). Each theme is a self-contained folder of tokens, components, anti-patterns, and a worked example; only the chosen theme's files are read (progressive disclosure). The choice persists in session memory and can be saved per-project to `.claude/use-html-theme.local.md`. Overrides via natural language and `[theme: <name>]` / `[notheme]` inline flags; ask to preview or compare the themes to get a side-by-side catalog page. Do NOT activate for markdown, JSON, prose, or non-HTML code, or when the user said `[notheme]` or asked for no theme.
Walk a pile of open questions or undecided to-dos one at a time via the AskUserQuestion tool — smartest question first, just-enough context per item, and after EVERY answer re-evaluate the remaining pile (drop what became moot, reorder what changed, surface implied follow-ups). Sources it handles — mine open questions from the current conversation, read them from a document the user points at (PRD, design doc, notes), take a list given inline, or pull undecided items from task systems (tasks, PROJECTS.md). Decisions are recorded back at their source. Use when the user says "go through these one by one", "walk me through the open questions", "there's a bunch of to-dos, help me decide", "triage these decisions with me", or a doc/plan is blocked on several unanswered questions. Not for scoping a project idea (project-refine), not for batch shareable decision pages (html-codesign — offer it if they'd rather review async), and context style defers to the explain skill's anatomy.
Resolve a repo name to its local path(s) and identity facts — origin, default branch, checkout-vs-worktree kind, branch, dirty state, build tooling — with one fast config-bounded command instead of exploring the filesystem. Fire whenever a repo is referenced by bare name and its location isn't already established in this session — BEFORE running ls/find/glob over home or code directories to locate a repo, BEFORE gh repo view/list to identify an origin or enumerate org repos, and for "where is <repo>", "what repos do I have", "which org owns X", "is this a worktree", "what's the exact name to clone". Covers local multi-root scan plus a gh REST-first remote org fallback from user config. Not for searching file contents inside an already-located repo, and not for cloning or mutating anything — it only finds and describes.
| name | using-project-harness |
| description | Bootstraps the project-harness bundle by establishing its five skills, running a four-step idempotent setup on first use per repo, and routing project-state edits through the right sibling skill. |
| when_to_use | When the user mentions a project, plan, roadmap, milestone, or backlog as tracked work, starts a repo session with project-management state, or is about to edit PROJECTS.md/projects/. Does not handle VM/Lima/sandbox execution setup; route that to a separate sandbox plugin. |
| allowed-tools | Read Write Bash AskUserQuestion |
Core principle: project-harness is a system, not a grab bag.
Editing PROJECTS.md or files in projects/ by hand bypasses the
discipline that makes the system reliable. Route every project-state
change through one of the four workflow skills.
IF A PROJECT-HARNESS SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
This is not negotiable. This is not optional. You cannot rationalize your way out of this.
User instructions in CLAUDE.md, AGENTS.md, or direct chat
override these conventions. The rule is: user > skills > default.
If the user says "don't run audit", don't run audit. The user is
in control.
The word “project” is not sufficient by itself. Use this bundle when the user
means tracked work in PROJECTS.md or projects/. If they mean creating a
Lima/VM sandbox, installing agents in that guest, choosing repositories to clone
into it, or launching a goal there, route to sandbox-lima, sandbox-prepare,
or sandbox-project from a separately installed sandbox plugin instead; those
skills are not shipped by project-harness. Once the sandbox work itself becomes
backlog or milestone state, project-harness may track that work without taking
over VM execution.
| Skill | Use when… |
|---|---|
using-project-harness | starting a session, or about to hand-edit PROJECTS.md |
project-next | the user asks "what's next?" / "what should I work on?" |
project-add | the user has an idea to capture |
project-refine | the user wants to flesh out / scope / decompose a project |
project-audit | the user asks "is everything in order?" / "audit" |
Skill priority within the bundle: using-project-harness orients the
session, project-next orients within the trunk, then one of
project-add / project-refine / project-audit runs based on the
user's intent.
On invocation, run the four-step bootstrap if the per-repo
config file .project-harness/project-harness.config.json does
not exist OR has init_done: false:
templates/PROJECTS.md
if missing.project-harness.project-audit's job).Each step is idempotent — completed steps are recorded in the config file and skipped on subsequent runs. A fully-bootstrapped repo costs one config-file read.
See references/bootstrap.md for the full procedure: the config
schema, the standard pointer block written to AGENTS.md/CLAUDE.md,
the planning-system branches, and the re-init escape hatch.
project-add has its own bootstrap path for the case where the
user invokes it directly in a fresh repo. The two paths are
equivalent; this one runs when the user enters via
using-project-harness.
These thoughts mean STOP — you're rationalizing:
| Thought | Reality |
|---|---|
| "I'll just edit PROJECTS.md to add this row" | project-add reserves the next ID atomically and avoids merge collisions. Editing by hand loses that. |
"I'll flip the trunk glyph from [?] to [ ] myself" | project-refine enforces the explicit-promote gate. Hand-flips skip the scope walkthrough. |
| "I'll just rename the file" | Filename, trunk row, and cross-references must update in lockstep. Use project-refine. |
| "These drift findings look obvious, I'll fix them all silently" | project-audit asks per finding because intentional drift exists and you cannot tell it from forgotten drift. |
| "I'll work on P21 now and capture the new idea later" | Capture is cheap. Use project-add first, then return. Lost ideas are the bigger cost. |
"I'll skip project-next and ask the user directly" | project-next brings the trunk and recent-touch info into context. Asking blind costs a turn. |
| "This is just a small edit" | Small edits are how drift starts. The cost of running the right skill is one extra round-trip; the cost of drift is hours of audit later. |
| "AGENTS.md/CLAUDE.md mentions look fine, I'll skip step 2" | The stale rule is mechanical: file missing OR doesn't contain project-harness. Don't second-guess it from prose vibes — let the rule fire and either confirm or decline once. |
| "They said project while setting up a Lima VM, so this must fire" | Execution-environment setup belongs to the sandbox-* skills; only tracked project state belongs here. |
| "I'll write the standard block into AGENTS.md without asking" | Bootstrap writes are gated on [y/n]. Silent edits to repo-level docs are exactly the surprise behavior the project's CLAUDE.md warns against. |
| "User picked 'other' for planning system, I'll guess where their plans live" | Don't guess. Ask one follow-up for the paths and persist the answer. The references-block helper depends on this being correct. |
The four workflow skills point at other frameworks for execution. They never invoke them.
| Want to do… | Reach for… |
|---|---|
| Decide what to work on | project-next (this bundle) |
| Capture an idea | project-add (this bundle) |
| Flesh out / scope / decompose | project-refine (this bundle) |
| Verify state is consistent | project-audit (this bundle) |
| Write a spec or implementation plan | Superpowers (writing-plans) |
| Execute a plan / write code | Superpowers (executing-plans), Claude Code, your editor |
| Run tests | Your test runner directly |
| Truly inline edits to a project file (e.g. fix a typo) | Just edit the file |
The last row is real: trivial edits like fixing a typo in a description don't need a skill. The skills exist for state changes (adding, scoping, decomposing, auditing) — not character-level fixes.
If PROJECTS.md is missing the project-harness pointer block, paste
this into the Conventions section so future contributors know the
bundle exists:
### Project workflow skills (plugin: project-harness)
- `using-project-harness` — bootstrap: when to use which skill below
- `project-next` — orient: what's in progress, what's next, what's recently touched
- `project-add` — capture an idea (≤4 questions, reserves the ID with a commit)
- `project-refine` — flesh out / scope / decompose an existing project
- `project-audit` — verify state matches conventions; fix per finding
The full initial-state trunk (with status legend, conventions, and
this pointer block) is at templates/PROJECTS.md in the plugin.
skills/_conventions.md and the per-skill
SKILL.md files, plus the trunk's own conventions section.AGENTS.md, CLAUDE.md, PROJECTS.md, or any
other repo file without an explicit [y/n] confirmation per step.
Silent writes to repo-level documentation would surprise users.**References** blocks in existing projects.
That's project-audit's job (run
project-audit --all --references-block after the bootstrap).references/bootstrap.md for the re-init escape
hatch.sandbox-*
workflow's responsibilities._conventions.md — shared prose conventions for the four workflow
skills.templates/PROJECTS.md — initial-state trunk to copy into a fresh
repo.references/bootstrap.md — full four-step bootstrap procedure,
config schema, AGENTS.md/CLAUDE.md standard block, planning-system
branches.skills/project-audit/references/references-block.md — format
spec and discovery helper for the per-project **References**
block; pointed at by step 4 of the bootstrap.