AI Agents Workflow

Keep repo-level context in one place once the repo has been initialized.

This pack supports VS Code + Copilot, Claude Code CLI, and Codex CLI. Copy it into a target repo under .github/harness_coding_instructions so the agent can route requests to the right workflow file and follow a more consistent process.

VS Code · Claude Code CLI · Codex CLI · Setup · Architecture

English | 简体中文

What Is This Pack For?

harness_coding_instructions is a portable instruction pack for coding agents. Copy it into a target repository so the agent can route requests through consistent workflows for implementation, debugging, questions, correctness checks, refactors, initialization, command execution, and PR breakdowns.

Architecture

The source repo stores the pack at the repo root. The installed layout expected by the scripts and CLI entry points is:

<target-repo>/
|-- .github/
|   |-- copilot-instructions.md
|   `-- harness_coding_instructions/
|       |-- AGENTS.md
|       |-- CLAUDE.md
|       |-- copilot-instructions.md
|       |-- setup.sh
|       |-- cli_setup.sh
|       |-- _lib/
|       |-- philosophy/
|       |-- workflow/
|       |-- agents/
|       |-- request_template/
|       |-- skills/
|       `-- repo_info/
|-- AGENTS.md
|-- CLAUDE.md
`-- .claude/
    `-- rules/

AGENTS.md and CLAUDE.md at the target repo root are generated by cli_setup.sh. .github/copilot-instructions.md is generated by setup.sh or cli_setup.sh.

Quick Start

Copy this repo's contents into a target repo at .github/harness_coding_instructions/.

Example from a Unix-like shell:

cd /path/to/target-repo
mkdir -p .github
rsync -a --exclude .git /path/to/coding_prompts/ .github/harness_coding_instructions/

For VS Code + Copilot:

bash .github/harness_coding_instructions/setup.sh

For Claude Code CLI, Codex CLI, or Codex in VS Code:

bash .github/harness_coding_instructions/cli_setup.sh

Then run the initialize workflow once in the target repo so repo_info/ contains target-specific memory:

Following the instructions in @/.github/harness_coding_instructions/workflow/vscode_workflow/initialize.instructions.md, initialize this repo.

For CLI tools, ask naturally from the target repo root after setup:

claude
# or
codex

Supported Environments

Environment	Entry point	Workflow directory	Notes
VS Code + Copilot	.github/copilot-instructions.md	workflow/vscode_workflow/	Primary VS Code router.
VS Code fast mode	Request templates with mode: fast	workflow/vscode_token_effective_workflow/	Faster, more parallel workflow variants.
Claude Code CLI	Root CLAUDE.md	workflow/claudecode_workflow/	Uses Claude Code native mechanisms and Claude-only skill steps.
Codex CLI / Codex in VS Code	Root AGENTS.md	workflow/codex_workflow/	General Codex workflows with manual review fallbacks where Claude skills do not apply.
Codex fast mode	Root AGENTS.md with mode: fast	workflow/codex_token_effective_workflow/	Token-effective Codex workflows for CLI and Codex in VS Code.
Aider or generic LLMs	Manual file references	Any workflow file	The Markdown can be followed manually, but subagent orchestration is not wired.

What Is In This Repo

Path	Purpose
copilot-instructions.md	VS Code Copilot router template.
CLAUDE.md	Claude Code CLI router template copied to the target repo root by cli_setup.sh.
AGENTS.md	Codex CLI router template copied to the target repo root by cli_setup.sh.
_lib/	Shared workflow contract, safety rules, and approval-gate rules.
philosophy/	Shared behavioral guidance used by workflows and subagents.
workflow/	Tool-specific workflow instruction families.
agents/	Custom agent definitions plus agents/INDEX.md.
request_template/	Fill-in request templates, including mode: general and mode: fast selection.
skills/	Skill definitions, including PR breakdown and Claude-native post-implementation skill orchestration.
.claude/rules/	Claude Code path-scoped rules copied to target repos by cli_setup.sh.
setup.sh	Configures VS Code workspace settings and generated Copilot instructions in a target repo.
cli_setup.sh	Generates CLI entry points and ensures target repo_info/ files exist.
repo_info/	Local/generated repo memory files. This directory is ignored by git in this source repo.

Workflow Families

Each workflow family currently contains these instruction files:

code.instructions.md
correctness_check.instructions.md
debug.instructions.md
exec.instructions.md
initialize.instructions.md
pr.instructions.md
query.instructions.md
refactor.instructions.md

The five workflow families are:

Directory	Intended use
workflow/vscode_workflow/	Full VS Code Copilot workflows.
workflow/vscode_token_effective_workflow/	Streamlined VS Code workflows selected by request templates with mode: fast.
workflow/claudecode_workflow/	Claude Code CLI workflows.
workflow/codex_workflow/	Codex CLI workflows.
workflow/codex_token_effective_workflow/	Streamlined Codex workflows selected by mode: fast under Codex CLI or Codex in VS Code.

The root routers classify the six common categories: initialize, code implementation, debug, query, correctness check, and refactor. The PR workflow exists as pr.instructions.md in every workflow family and is exposed through request_template/pr_request_template.md or by directly referencing the PR workflow file.

Setup Scripts

setup.sh

Run from the target repo root after copying the pack to .github/harness_coding_instructions/.

It validates that the pack is present, then writes or updates .vscode/settings.json with:

{
  "chat.instructionsFilesLocations": {
    ".github/harness_coding_instructions": true,
    ".claude/rules": true
  },
  "chat.agentFilesLocations": {
    ".github/harness_coding_instructions/agents": true
  },
  "chat.includeReferencedInstructions": true
}

It also creates or refreshes .github/copilot-instructions.md when that file is generated by this pack. Existing custom Copilot instructions are left unchanged.

When merging an existing VS Code settings file, the script tries python3, then node, then jq. If none are available, it prints manual settings to add.

cli_setup.sh

Run from the target repo root after copying the pack to .github/harness_coding_instructions/.

It:

• Detects whether claude or codex is on PATH.
• Creates or refreshes root CLAUDE.md and AGENTS.md when they are generated by this pack.
• Creates or refreshes .github/copilot-instructions.md when appropriate.
• Copies .claude/rules/*.md into the target repo.
• Ensures the eight canonical repo_info/ files exist under the installed pack.

Existing custom files are not overwritten unless they contain this pack's generated markers.

Request Templates

request_template/ contains user-facing prompt templates:

code_request_template.md
correctness_check_request_template.md
debug_request_template.md
initialize_request_template.md
pr_request_template.md
query_request_template.md
refactor_request_template.md

Templates use:

mode: general

or:

mode: fast

For VS Code Copilot, general selects workflow/vscode_workflow/ and fast selects workflow/vscode_token_effective_workflow/. For Codex CLI or Codex in VS Code, general selects workflow/codex_workflow/ and fast selects workflow/codex_token_effective_workflow/. The templates use @/.github/harness_coding_instructions/... paths for VS Code Copilot and filesystem paths for Codex.

Agents And Skills

agents/ defines coordinator agents and worker agents. Coordinator agents include Code Workflow, Debug Workflow, Refactor Workflow, Query Workflow, and Correctness Workflow. Worker agents include Focus Analyst, Broad Analyst, Free Analyst, Senior Engineer, Principal Engineer, Devils Advocate, Online Researcher, Implementer, QA Engineer, Bug Reproducer, and several refactor-focused analysts.

See agents/INDEX.md for the complete registry.

skills/ currently contains:

• breakdown-pr: analyzes a large branch or PR and proposes a stacked PR breakdown.
• claude-native-skills-subagents: Claude Code-only post-implementation orchestration for native skills such as /simplify, /batch, /debug, and /claude-api.

Repo Memory

Workflows use repo_info/ as persistent repo memory. cli_setup.sh ensures these canonical files exist in the installed pack:

codebase_overview.md
known_issues.md
known_issues_auto_generated.md
past_Correctness_Check.md
past_Q&A.md
scripts_overview.md
update_logs.md
update_logs_auto_generated.md

In this source repo, repo_info/ is ignored by git. In a target repo, initialize or refresh it for that specific codebase before relying on later workflows.

Path Rules

• In this source repo, paths are root-relative, for example workflow/codex_workflow/code.instructions.md or workflow/codex_token_effective_workflow/code.instructions.md.
• In an installed target repo, the pack lives under .github/harness_coding_instructions/.
• VS Code workflow prompts may use @/.github/harness_coding_instructions/....
• CLI entry points use filesystem-relative paths such as .github/harness_coding_instructions/workflow/codex_workflow/code.instructions.md and .github/harness_coding_instructions/workflow/codex_token_effective_workflow/code.instructions.md.
• Do not add VS Code @/ prefixes to CLI workflow files.

Safety Rules

The shared workflow contract and safety rules require:

• Do not try to commit changes to GitHub.
• Do not write spam files into the repo.
• Do not use sudo.
• For code, debug, and refactor workflows, print the finalized plan before implementation. If the user requested no code changes, stop after the plan; otherwise continue.

Keep destructive auto-approval disabled for any command that can delete or overwrite user files.

Limitations

• This repo is an instruction pack, not an application. There is no package manifest, runtime, build command, or formal test suite.
• The setup scripts are Bash scripts.
• CLI subagent behavior depends on the capabilities of the active CLI tool and model parity support.
• Claude-native skill steps only apply in Claude Code environments.
• The source repo ignores .github/ and repo_info/, so generated target-repo files are not tracked here.
• Root AGENTS.md and CLAUDE.md in this source repo are templates for installed target repos; their .github/harness_coding_instructions/... paths are expected to resolve after installation.

Typical Usage

For normal work, ask naturally and let the active router classify the request. Use request templates when you want strict mode selection or when you want to force the agent to read a specific workflow file first.

Examples:

Update the README based on this repo.

mode: fast

Follow the corresponding debug.instructions.md and fix the failing test described below.

Use request_template/pr_request_template.md to break this branch into reviewable PRs.