SuperAPI AI Directory

harness-init

Coding & development

View repository

Updated 10-19 01:10

About this skill

harness-init

A minimalist repository template for Agent-collaborative development. Humans set direction, Agents execute. Rules, knowledge, and change records are all versioned.

The template itself ships without scripts or a Makefile — this is an AI collaboration template, and all files are created by the Agent following the guidance.

Two modes

  • The user explicitly mentions the harness-init、harness template, or asks to create a project following this template → Initialization mode
  • The current repository is already a harness-init structure → Collaboration mode
  • For a plain "create project", "initialize repository", or "build a skeleton", do not trigger; treat it as a normal project

Initialization mode

Create an Agent-first project skeleton from scratch.

Step 1: Confirm basic information

Confirm with the user:

  1. Project name (required)
  2. Project type (required, e.g., Web/API, frontend-backend separation, desktop, CLI/tool, library/SDK)
  3. Whether a frontend interface or other specialized constraints are needed

Step 2: Create the directory structure

<project>/
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── CODEOWNERS
├── LICENSE
├── .editorconfig
├── .gitattributes
├── .gitignore
├── .markdownlint.json
└── docs/
    ├── ARCHITECTURE.md
    ├── HISTORY_GUIDE.md
    ├── PLANS_GUIDE.md
    ├── REPO_COLLAB_GUIDE.md
    ├── exec-plans/
    │   ├── README.md
    │   ├── tech-debt-tracker.md
    │   ├── active/        # 空目录,放 .gitkeep
    │   ├── completed/     # 空目录,放 .gitkeep
    │   └── templates/
    │       └── execution-plan.md
    └── histories/
        └── template.md

Only the 4 "soul" documents plus ARCHITECTURE to guard the architecture. Other topic documents (SECURITY, RELIABILITY, CICD, FRONTEND, etc.) are added on demand once the real project takes shape; do not lay down placeholders during initialization.

Step 3: Instantiate key documents according to project type

Do not just perform template name substitution. You must turn these documents into project-specific content:

  • README.md: real project introduction, startup method, directory structure
  • AGENTS.md: retain the navigation role, and clarify this project's most critical plan / history constraints
  • docs/ARCHITECTURE.md: real module boundaries, runtime topology, data flow

Add on demand (not in the default skeleton; add after the project takes shape):

  • Web / API / backend services → docs/RELIABILITY.md、docs/SECURITY.md、docs/CICD.md
  • Frontend-backend separation / includes frontend → docs/FRONTEND.md、docs/RELIABILITY.md、docs/CICD.md
  • Desktop / client → docs/DESIGN.md、docs/RELIABILITY.md、docs/SECURITY.md
  • CLI / SDK / library → docs/DESIGN.md、docs/CICD.md

If the project type is still unclear, do not pretend initialization is complete; first clarify the project type, then decide whether to add these documents.

Step 4: Generate file contents

Read references/init-files.md to obtain the full content of each file. When generating, note:

  • Replace {{PROJECT}} with the project name
  • All documents use Chinese
  • Line endings LF
  • .editorconfig: UTF-8, 2-space indentation
  • Documents determined in Step 3 to be instantiated must be written as project-specific content, with no template placeholders left
  • references/init-files.md only provides the full content of the default slim skeleton; optional topic documents added according to project type must be newly written based on real project facts — do not pretend that the template already contains full content for them

Step 5: Manually verify the skeleton

Against the structure checklist from Step 2, confirm:

  • All 4 soul documents (AGENTS.md + REPO_COLLAB_GUIDE.md + HISTORY_GUIDE.md + PLANS_GUIDE.md) are present
  • ARCHITECTURE.md has been instantiated with project content
  • docs/exec-plans/ The 3 subdirectories under
  • docs/histories/template.md exists
  • Infrastructure files (.gitignore, .editorconfig, etc.) are present

Step 6: Tell the user the next steps

  1. Confirm that the three documents README, AGENTS, and ARCHITECTURE have been instantiated
  2. Replace the placeholder team name in CODEOWNERS placeholder team name in
  3. Create as needed apps/、packages/、infra/ to hold real code
  4. After real business is integrated, supplement according to project type docs/SECURITY.md and other topic documents

Collaboration Mode

Conventions to follow when working in a repository that already has the harness-init structure.

Must-read at the start of each task round

Read in order to build context:

  1. AGENTS.md — navigation entry (routing only, no rules)
  2. docs/REPO_COLLAB_GUIDE.md — collaboration conventions
  3. docs/ARCHITECTURE.md — architecture overview

Must-read before code changes are complete

docs/HISTORY_GUIDE.md — when to record history, how to name it, how to redact it

Read selectively as tasks require

Scenario Document
Complex multi-step tasks docs/PLANS_GUIDE.md
Topic documents extended by the project itself See the files that exist at that time under docs/ files that existed at that time under

Core Work Rules

  1. Land knowledge in the repository: important information that exists only in chat logs and in your head is as good as nonexistent
  2. Keep documents in sync: when behavior changes, update code, documents, and history in the same round
  3. Prefer simple solutions: choose simple, clear, observable solutions; do not pile on complexity
  4. When an Agent repeatedly fails: prioritize fixing the environment, fixing the guidance, and fixing the conventions; do not rely on prompts alone
  5. AGENTS.md does routing only: do not pile up rules; docs/ is the source of knowledge
  6. Do not depend on scripts: templates do not include Makefile/scripts; all files are created by the Agent according to the guidance

Complex Tasks: Create an Execution Plan

Trigger conditions (any one applies):

  • The task spans multiple commits or work rounds
  • Involves high-risk changes such as architecture, protocols, or data migration
  • Requires phased verification, rollback strategy, or decision audit
  • Multi-person or multi-Agent collaboration

Procedure:

  1. Copy docs/exec-plans/templates/execution-plan.md
  2. Name it docs/exec-plans/active/YYYY-MM-DD-<slug>.md
  3. Move it to when complete docs/exec-plans/completed/

Read references/conventions.md to learn the detailed format of the execution plan.

After Repository Changes: Record Change History

Record every task that completes substantive repository changes:

  1. Copy docs/histories/template.md
  2. Create the directory docs/histories/YYYY-MM/(if it does not exist)
  3. Name it YYYYMMDD-HHmm-<task-slug>.md

Content includes: user request (after redaction), main code/document changes, design intent, and key affected files.

No need to recordscenarios: pure Q&A/research tasks (no actual changes to repository content).

Confirm before committing

  • Documents have been updated in sync
  • Change history has been recorded
  • Examples and documentation are consistent with the current implementation

Reference Files

  • references/init-files.md — all file contents required for initialization mode
  • references/conventions.md — detailed conventions, templates, and workflows for collaboration mode