agent-instructions (@damphuquy/agent-init)
Spec-Anchored Cognitive Harness (SACH-2026) v4.4.1
Install
Bootstrap the Software Engineering workspace in a repository:
npx @damphuquy/agent-init . --role swe --lang en
Other supported entry points:
npx @damphuquy/agent-init . --role ba --lang en
npx @damphuquy/agent-init sync .
npx @damphuquy/agent-init . --force
What the package provides
The package copies project instructions, schemas, optional host hooks, offline validators, and workflow templates. Root AGENTS.md provides task guidance and explicit routes into skills and protocols. The CLI dispatches commands when invoked with their flags. The package does not include a natural-language command router, model service, or general-purpose agent scheduler.
Use verification proportional to task risk. Machine validators check declared structure and conditions; they do not prove program correctness, run every project test, or authenticate a person. The optional loop guard requires a compatible host adapter. Git worktrees separate checkout files but do not isolate credentials, processes, or services. See the capability matrix for details.
Skill and feature routing
The SWE template separates these responsibilities:
- Root AGENTS.md owns task sizing, execution guidance, verification expectations, and explicit file routes.
- The harness skill owns skill authoring, trigger evaluation, and harness-contract design.
- The evolve skill owns evidence-based retrospectives and proposed changes to instructions, skill routes, or protocols.
- The skills manifest inventories declared skill bundles. skills-check validates local metadata and file presence; neither action proves native host activation.
- Third-party skill collections such as mattpocock/skills are advisory and opt-in. The SWE template does not bundle or activate them; SACH remains the owner of its task routes and lifecycle.
- The CLI routes explicit research, debate, QA, graph-index, task, and gate commands. Listing commands does not automatically select them from natural language.
The current research command produces a dossier scaffold with placeholder sources and claims; it does not browse. Debate builds a deterministic challenge ledger; its review lenses are not independent reviewers. The optional subagent flags format worker prompts but do not dispatch agents. The QA command defaults to L1, L2, L3, and L6. The graph index is syntactic navigation data. Each output needs review against source and command evidence.
For the external-skill policy, trigger evaluation, and route evidence levels, see Advanced Workflows and Architecture and Routing Evidence. Live activation must be checked in a named host.
Task-sized workflow
For a small change, state the outcome, scope, and relevant check in the conversation or a concise task note. For multi-step work, use .agents/TASK.md or create a task artifact. Reproduce reported bugs, define feature acceptance before implementation, and use relevant checks for docs/config changes.
For tasks that use gate questions, show the questions and record a real engineer-selected answer before verifying:
npx @damphuquy/agent-init gate questions <slug> --gate G1
npx @damphuquy/agent-init gate answer <slug> --gate G1 --question-id <id> --option "<chosen option>"
npx @damphuquy/agent-init verify-gate G1
In an interactive TTY, verify-gate G1 --interactive can prompt for pending questions. The prompt is skipped in CI and non-TTY environments. The recorded signer is a label, not authenticated identity. The current gate ask command automatically records the first option when no option is supplied; it is not a human prompt and must not be used as evidence of explicit approval.
CLI commands
# Initialize or synchronize workspace instructions
npx @damphuquy/agent-init . --role swe --lang en
npx @damphuquy/agent-init sync .
# Task lifecycle and local worktree
npx @damphuquy/agent-init task create <slug> [--title <text>] [--require-signoff]
npx @damphuquy/agent-init task status <slug>
npx @damphuquy/agent-init task sandbox <slug>
npx @damphuquy/agent-init task approve <slug> --gate <G0|G1|G2|G3> [--signed-by <name>]
npx @damphuquy/agent-init task complete <slug>
# Explicit feature commands
npx @damphuquy/agent-init research --topic "<question>" [--depth <n>] [--subagents]
npx @damphuquy/agent-init graph-index [--src <dir>] [--output <file>] [--fallback]
npx @damphuquy/agent-init debate [--task <file>] [--tier <0|1|2>] [--subagents]
npx @damphuquy/agent-init qa [--layers L1,L2,L3,L6] [--task <file>] [--output <file>]
npx @damphuquy/agent-init run-test -- npm test
# Gate question and verification flow
npx @damphuquy/agent-init gate questions <slug> [--gate <G0|G1|G2|G3>]
npx @damphuquy/agent-init gate answer <slug> --gate <G0|G1|G2|G3> --question-id <id> --option <text>
npx @damphuquy/agent-init verify-gate G0
npx @damphuquy/agent-init verify-gate G1 --interactive
npx @damphuquy/agent-init verify-gate G2
npx @damphuquy/agent-init verify-gate G3
Offline Python helpers can validate local artifacts without a model call or live web access:
python3 .agents/harness.py validate --spec spec.json --task task.json
python3 .agents/harness.py handoff-check --input handoff.json --strict
python3 .agents/harness.py qa-verdict-check --input qa-verdict.json --strict
python3 .agents/harness.py skills-check --input .agents/skills-manifest.json --root . --strict
python3 .agents/harness.py research-dossier --input research-dossier.json --strict
python3 .agents/harness.py debate-eval --input debate-ledger.json --strict
Documentation
- Hands-on Walkthrough
- Daily Cheat Sheet
- Advanced Workflows
- Architecture and Routing Evidence
- Capability Matrix
- Tutorial Version Manifest
- Verified Research and Implementation Report
- DevOps and Release Automation
Versioning and upgrades
Bootstrapped projects include an instruction-version.json manifest. Review local changes before updating a project; task files, custom skills, and project commands may be user-owned. Use the package update flow or re-run the initializer with a reviewed overwrite plan.
npx @damphuquy/agent-init update --check
npx @damphuquy/agent-init update
License
Licensed under the MIT License.