setup-superharness

name	setup-superharness
description	Set up superharness in a project: scan the codebase to discover conventions and tech stack, write findings into .superharness/spec/, then distill them into AGENTS.md and CLAUDE.md. Use when the user asks to set up superharness, to scan or re-scan the codebase for conventions, or to generate or refresh AGENTS.md / CLAUDE.md.

Setup Superharness

One-stop toolkit that prepares a project for superharness. One discovery pass feeds two outputs: .superharness/spec/ holds the full record, and AGENTS.md carries a digest of it that any AI tool reads natively.

Project specs are living documents, not static templates. Every time this skill runs, it compares what the codebase actually does against what the spec files document. The gap between "what the spec says" and "what the code does" is what this skill closes.

This skill supports multiple ecosystems (JS/TS, Python, Java, and others). Language-specific detection knowledge is in ./reference/ files.

When This Runs

Only when the user invokes /superharness:setup-superharness. It is a standalone toolkit outside every workflow: run it once before the first feature work, and again whenever conventions need a re-scan.

Process

Step 0: Detect Project Type

Before scanning, determine what kind of project this is so you know what to look for.

1. Read .superharness/config.yaml and check the project.type field
2. If type is explicitly set (not auto), use that type and load the matching reference file
3. If type is auto, check which manifest files or project bundles exist in the project root (note: .xcodeproj and .xcworkspace are directory bundles, match by extension on directories):

Manifest file(s) / bundle(s) present	Ecosystem	Reference to load
package.json	JS/TS	./reference/js-ts.md
pyproject.toml, setup.py, requirements.txt, Pipfile	Python	./reference/python.md
pom.xml, build.gradle, build.gradle.kts	Java/Kotlin	./reference/java.md
Package.swift, *.xcodeproj/, *.xcworkspace/	Swift (iOS/macOS)	./reference/swift.md
None of the above	Unknown	No reference file

4. If multiple manifest types are present (e.g., both package.json and pyproject.toml), load all matching references -- this is a polyglot or fullstack project
5. Log the detected ecosystem(s) in your initial output

Fallback for unknown ecosystems: If no reference file matches, you still run discovery using your general programming knowledge. Identify the same categories (language, framework, testing, code organization, etc.) -- you just don't have a lookup table for framework detection signatures.

Step 1: Determine Spec State

Read .superharness/spec/ files. If the directory doesn't exist, tell the user to run superharness init first and stop.

Check whether spec files are skeletons (only contain TODO comments, <!-- TODO -->, or empty checklists with no real content) or populated (have substantive content describing actual project conventions).

• Skeleton -> go to Step 2 (Full Discovery)
• Populated -> go to Step 3 (Incremental Check)

Step 2: Full Discovery

The spec files are empty. Scan the project and build an initial picture of what conventions exist.

If a reference file was loaded in Step 0, follow its guidance:

• Use the Manifest Files table to know what files to scan and what to extract from each
• Use the Framework Detection Signatures table to identify the specific framework
• Use the Detection Dimensions list to know what categories to identify
• Use the Example Output as a format guide

If no reference file was loaded, scan using general knowledge:

• Look for build/config files in the project root to identify the language and build system
• Identify the primary framework from file extensions, directory structure, and dependencies
• Check for testing frameworks, linting tools, and CI/CD configuration
• Examine a few representative source files for code organization patterns

In all cases, also check these universal sources:

Source	What to look for
Dockerfile / docker-compose.yml	Deployment patterns
.github/workflows/ / .gitlab-ci.yml	CI/CD pipeline
README.md	Project description, setup instructions
.gitignore	What's excluded (hints at tooling)
A few representative source files	Code organization, import patterns, error handling

Present findings to user in Chinese:

"我分析了项目代码，发现以下约定:

• 语言/框架: [detected language and framework]
• 包管理/构建: [detected package manager or build tool]
• 测试: [detected testing framework and patterns]
• 代码质量: [detected linting/formatting/type-checking tools]
• API 风格: [detected API patterns, if applicable]
• 代码组织: [detected project structure and module patterns]

是否将这些写入 .superharness/spec/? 后续可以随时修改。"

Adjust the categories based on what the reference file's Detection Dimensions specify. Not all categories apply to every project -- omit dimensions that aren't relevant.

Only write after user confirms. If the user says no or wants changes, adjust and ask again, or skip entirely.

Write each discovery into the most relevant spec file. For example:

• State management -> spec/components/state-management.md (if it exists)
• API style -> spec/api/design.md (if it exists)
• General patterns -> spec/guides/index.md

If the matching spec file doesn't exist, write to the closest match or spec/guides/index.md.

Commit the updated files after writing, then continue to Step 4.

Step 3: Incremental Check

The spec already has content. Do a quick comparison: what does the code do now vs. what does the spec say?

1. Read the current spec files to know what's already documented
2. Quick-scan for changes since last check:
   • New dependencies in the project's manifest file(s) not mentioned in spec
   • New config files or major directory changes
   • Changed patterns (e.g., migrated testing framework, added new tooling)
3. If new or changed patterns found, present them one by one in Chinese:

   "发现项目新增了 [X] 模式，当前 spec 中未记录。是否更新?"

4. User confirms -> update the specific spec file and commit
5. User declines -> skip, continue to next finding
6. Nothing new -> report "项目规范已是最新"

Either way, continue to Step 4.

The incremental check should be noticeably faster than full discovery -- under a minute for most projects. Don't re-read every source file; focus on manifest and config changes as signals.

Step 4: Review Learnings (promote and retire)

.superharness/spec/learnings/ accumulates conventions the learn skill captured mid-conversation. Learn captures; setup consolidates in both directions: stable conventions get promoted into spec proper, and stale or redundant pages get retired. Promotions also carry into the Step 5 digest.

Skip to Step 5 when the directory is missing or empty.

Promote.

1. Read every topic page whose frontmatter has no promoted_to field.
2. A candidate states a project convention -- how the project is or does things -- at confidence 0.7 or higher. Process experience (pitfalls, debugging stories, one-off fixes) stays in learnings.
3. Present each candidate in Chinese, converted to descriptive spec tone:

   "learnings 中记录了约定 [X]（confidence [n]），建议沉淀到 spec/{target-file}。是否沉淀?"

4. User confirms -> write the convention into the most relevant spec file (same routing as Step 2), add promoted_to: <spec-file> to the topic page's frontmatter, and commit both.
5. User declines -> leave the topic page untouched; a future run proposes it again.

Retire. While reading the pages, also flag ones that should leave the wiki:

• contradicts the current codebase -> propose correcting or deleting the page
• fully readable from the repo (skills, docs, spec, git history) -> propose deleting or absorbing it into the covering document
• long unreferenced and no longer recurring -> propose moving it down one confidence band

Present each flagged page in Chinese with the reason; act only on the user's per-page confirmation, then rewrite index.md (topics at confidence 0.7 or higher only).

Pending doc updates. When .superharness/spec/learnings/pending-doc-updates.md exists, walk its suggestion lines one by one: user confirms -> apply the change to the target document and remove the line; user declines -> remove the line. Delete the file when it empties.

This step is done when every topic at confidence 0.7+ is promoted, declined, or judged process experience, and every flagged page and pending suggestion is resolved.

Step 5: Distill into AGENTS.md and CLAUDE.md

Spec and digest share one source: build the digest from what .superharness/spec/ says now, excluding spec/learnings/ (process notes, too volatile for a project front page).

Build the digest. Condense the spec content into a compact project brief for AI tools. Let the structure follow what discovery actually found -- typical material includes project structure, everyday commands (build / test / lint), tech stack and coding conventions, testing habits -- and omit anything the spec doesn't cover. End with one line pointing to .superharness/spec/ for the full record.

Write AGENTS.md. The digest lives in a managed block:

<!-- superharness:begin -->
[digest]
<!-- superharness:end -->

• AGENTS.md missing -> create it; the file starts as just the managed block.
• AGENTS.md exists -> replace the content between the markers; when no markers exist yet, append the whole block at the end. Everything outside the markers belongs to the user -- the block is the only region this skill writes.
• Existing block already matches the new digest -> report "AGENTS.md 已与 spec 同步" and skip the write.

Write CLAUDE.md.

• CLAUDE.md missing -> create it with a single line: @AGENTS.md
• CLAUDE.md exists without an @AGENTS.md reference -> append that one line, everything else untouched
• CLAUDE.md already references AGENTS.md -> leave it alone

Confirm, then write. Show the user the proposed AGENTS.md block (and the CLAUDE.md change, if any) and wait for confirmation, same as every spec write. Commit after writing.

This step is done when the AGENTS.md managed block matches the current spec content and CLAUDE.md references AGENTS.md.

What Good Spec Entries Look Like

Good (records what IS):

## State Management

The project uses zustand for global state management.

- Store files are located in `src/stores/`
- Each store is a separate file, created with `create()`
- Components access stores via `useXxxStore` hooks

Bad (invents rules):

## State Management

All state management must use zustand. Redux and Context API are prohibited.
Store files must be placed in src/stores/.

Good (Python project example):

## Web Framework

The project uses FastAPI to build REST APIs.

- Routes are defined in `app/routers/`, organized by resource
- Uses Pydantic models for request/response validation
- Dependency injection via `Depends()`

The difference: good entries describe observed patterns that a new developer (or AI) can follow. Bad entries prescribe rules that may not reflect reality. This skill discovers -- it doesn't legislate. The same tone carries into the digest: AGENTS.md states what the project does, never what it should do.

Reference Files

Language-specific detection knowledge is in ./reference/ files in this directory:

• reference/js-ts.md -- JavaScript / TypeScript projects
• reference/python.md -- Python projects
• reference/java.md -- Java / Kotlin projects
• reference/swift.md -- Swift (iOS / macOS) projects

Each reference file contains:

1. Manifest Files table -- what files to scan and what to extract
2. Framework Detection Signatures table -- how to identify specific frameworks from dependencies/config
3. Detection Dimensions list -- what categories to identify for this ecosystem
4. Example Output -- sample discovery results in the expected format

Load the relevant reference file(s) in Step 0. If none match, use your general knowledge. To add support for a new language, create a new reference file following the same structure.

Constraints

• Speed over completeness. 2 minutes max for full discovery, 1 minute for incremental. If the codebase is large, focus on the most visible patterns and stop. The user can always run this again.
• Human in the loop. Every write -- spec, AGENTS.md, CLAUDE.md -- must be confirmed by the user. No silent updates.
• Facts only. Record "项目使用 X" not "应该使用 X". Describe what you observe, not what you think should be.
• Managed block only. In AGENTS.md, write inside the superharness:begin/end markers and nowhere else; in CLAUDE.md, the @AGENTS.md line is the only content this skill adds.
• Finish the requested setup cleanly. Return control after Step 5 completes or the user rejects the proposed updates.