headless-executor-contract

Defines behavioral rules for AI agents executing delegated background coding tasks.

Updated Jul 30, 2026
One-click install
npx skills add https://github.com/primax79/ai-architect-executor --skill headless-executor-contract-primax79
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: headless-executor-contract
Source: https://github.com/primax79/ai-architect-executor/tree/main/plugins/executor-side/skills/headless-executor-contract
Command: npx skills add https://github.com/primax79/ai-architect-executor --skill headless-executor-contract-primax79

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When an orchestrating AI (the Architect) delegates implementation work to a background coding agent (the Executor), the Executor often asks questions, drifts out of scope, or reports success without verifying anything. This Skill gives the Executor a strict behavioral contract so delegated tasks complete autonomously and report results in a machine-parseable format. ## Core Features & Use Cases - Zero-Interactivity Rules: Instructs the Executor to never ask the user questions and to make reasonable technical decisions independently based on the Architect's instructions. - Structured Final Report: Mandates a Final Report with Outcome, Files changed, Verification, and Issues sections, formatted precisely so the Architect can parse it programmatically. - Scope and Blast-Radius Discipline: Enforces staying within focus_files and task_instructions, investigating unfamiliar changes before overwriting, and documenting forced deviations under Issues. - Use Case: An Architect AI delegates a bug fix to a headless coding agent over MCP or a CLI wrapper; the Executor reads the focus files, implements only the specified change, runs the actual test suite, and returns a parseable Final Report marking the outcome as completed, partial, or failed. ## Quick Start Apply the headless-executor-contract when running as a background Executor agent so you follow its zero-interactivity, scope discipline, and Final Report rules for the delegated task.

Frequently Asked Questions about headless-executor-contract

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run an AI coding agent headless without it asking questions?▼

Apply a zero-interactivity behavioral contract that instructs the agent to make reasonable technical decisions from the delegating instructions instead of prompting a user. The agent runs in the background and resolves ambiguity on its own.

How should a background coding agent report task results to an orchestrator?▼

The agent should print a Final Report with Outcome, Files changed, Verification, and Issues sections in exact Markdown formatting. The orchestrating AI parses this final message programmatically, so formatting must be precise.

Does this contract work with MCP or CLI-based delegation?▼

Yes, the contract is protocol-agnostic and applies whether tasks are delegated over MCP, a CLI wrapper, or manually. It defines behavior, not transport mechanics.

What should an Executor agent do when a build keeps failing?▼

It should fail fast: stop retrying, mark the outcome as partial or failed in the Final Report, and explain the blocker under Issues so the orchestrating Architect can intervene with missing context.

When should an Executor agent not modify files outside its task scope?▼

It should never silently touch files outside the defined focus_files or stated scope, including deleting data or force-pushing. Forced deviations must be documented explicitly under Issues in the Final Report.