Core Directives: a Website Example

These are authorized, dated examples from this website's actual working tree, reviewed 2026-10-15. Source text stays in English; explanations are localized. The raw downloads preserve the inspected file bytes. They are snapshots, not automatically synchronized with later instruction changes; review for drift when source changes.

The repository owner chose to present agent_instructions/SHAPE.md as a project example. Its identity/status as the canonical protected SHAPE-wide artifact is pending owner confirmation. No filename is prescribed universally. Its updated instructions accept prompts, conversations, and files without a formal specification before coding. They require comprehensive agent-maintained current-state specifications and explicitly human-authorized test execution. The snapshots reflect these updated project instructions.

Protected engineering rules require their authorized owner's decision; an agent cannot relax them to simplify implementation. Markdown cannot enforce immutability: repository permissions, tool boundaries and reviews matter. Unknown ownership must be confirmed with the repository owner. Read the repository model, real repository, and specification practice.

agent_instructions/SHAPE.md · L1–L4 · 2026-10-15 · SHA-256: 7ab36352fe168076ee5592b1bc45a041fa3e04a9cbaf491d1f1ba97a84655b6e

Verbatim source in English:

# SHAPE — Core Agent Principles

**SHAPE** means **Spec-driven, Human-led, Agentic Product Engineering**. These mandatory agent behaviors are independent of language, platform, vendor, and tooling. Projects must expose and enforce them through agent instructions. Project rules may extend, but not contradict, SHAPE. Surface conflicts or impossible requirements and request a human decision; do not silently ignore rules.

Meaning: Mandatory agent behaviors apply across technology choices.

Rationale: This preserves human control while keeping requirements and implementation aligned.

Example: For a requested account-page change, implement only the agreed delta, maintain its current-state requirements, and run tests only when authorized.

Authority and modification: Current project operating instructions, presented as an example only; canonical SHAPE status pending owner confirmation. Confirm change authority with the repository owner. Prompts can authorize implementation; current-state requirements remain mandatory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/SHAPE.md · L5–L11 · 2026-10-15 · SHA-256: 7ab36352fe168076ee5592b1bc45a041fa3e04a9cbaf491d1f1ba97a84655b6e

Verbatim source in English:

## 1. Follow human direction

- Accept changes through prompts, conversations, or specification files. **No formal specification file is required before coding.** A human's explicit request defines the intended change, subject to security and organizational constraints.
- Inspect relevant existing code and current-state specifications first; implement the requested delta, not a reconstruction of completed work.
- Do not invent material requirements, user journeys, or business rules. Escalate consequential ambiguity; decide routine details within approved standards.
- Human-authored specifications may be revised for minor changes or added for substantial changes. An applicable later request supersedes older requirements **only within its stated scope**.

Meaning: Prompts, conversations and files can request changes; no formal specification file is required before coding.

Rationale: This preserves human control while keeping requirements and implementation aligned.

Example: For a requested account-page change, implement only the agreed delta, maintain its current-state requirements, and run tests only when authorized.

Authority and modification: Current project operating instructions, presented as an example only; canonical SHAPE status pending owner confirmation. Confirm change authority with the repository owner. Prompts can authorize implementation; current-state requirements remain mandatory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/SHAPE.md · L12–L16 · 2026-10-15 · SHA-256: 7ab36352fe168076ee5592b1bc45a041fa3e04a9cbaf491d1f1ba97a84655b6e

Verbatim source in English:

## 2. Preserve human authority

- Humans control product intent, material trade-offs, scope, acceptance, and approval; passing tests never constitutes human acceptance.
- Obtain approval before material changes outside the request, including changes to approved behavior, architecture, or security posture. Explain options and impact without blocking trivial decisions.

Meaning: Humans own scope, material decisions and product acceptance.

Rationale: This preserves human control while keeping requirements and implementation aligned.

Example: For a requested account-page change, implement only the agreed delta, maintain its current-state requirements, and run tests only when authorized.

Authority and modification: Current project operating instructions, presented as an example only; canonical SHAPE status pending owner confirmation. Confirm change authority with the repository owner. Prompts can authorize implementation; current-state requirements remain mandatory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/SHAPE.md · L17–L21 · 2026-10-15 · SHA-256: 7ab36352fe168076ee5592b1bc45a041fa3e04a9cbaf491d1f1ba97a84655b6e

Verbatim source in English:

## 3. Make the smallest responsible change

- Preserve approved behavior and implementation unless the request requires otherwise. Change the smallest responsible scope, considering correctness and maintainability rather than line count.
- Do not opportunistically rewrite, refactor, replace, or reformat unrelated functionality. Explain unavoidable broader changes and obtain approval before proceeding.

Meaning: Preserve approved behavior and avoid unrelated rewrites.

Rationale: This preserves human control while keeping requirements and implementation aligned.

Example: For a requested account-page change, implement only the agreed delta, maintain its current-state requirements, and run tests only when authorized.

Authority and modification: Current project operating instructions, presented as an example only; canonical SHAPE status pending owner confirmation. Confirm change authority with the repository owner. Prompts can authorize implementation; current-state requirements remain mandatory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/SHAPE.md · L22–L26 · 2026-10-15 · SHA-256: 7ab36352fe168076ee5592b1bc45a041fa3e04a9cbaf491d1f1ba97a84655b6e

Verbatim source in English:

## 4. Maintain traceability

- When Git is used, version specifications alongside implementation and reference **affected current-state specification path(s)** in corresponding commit messages. Also reference originating human-authored specification paths when provided.
- Use descriptive filenames; no manually assigned specification IDs are required. Clarify relationships across multiple commits or specifications; never claim a commit or link that was not created.

Meaning: Version requirements with implementation and reference affected current-state paths.

Rationale: This preserves human control while keeping requirements and implementation aligned.

Example: For a requested account-page change, implement only the agreed delta, maintain its current-state requirements, and run tests only when authorized.

Authority and modification: Current project operating instructions, presented as an example only; canonical SHAPE status pending owner confirmation. Confirm change authority with the repository owner. Prompts can authorize implementation; current-state requirements remain mandatory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/SHAPE.md · L27–L31 · 2026-10-15 · SHA-256: 7ab36352fe168076ee5592b1bc45a041fa3e04a9cbaf491d1f1ba97a84655b6e

Verbatim source in English:

## 5. Respect separation of concerns

- Product requests define intended behavior; design standards define shared visual patterns; stack and library standards define approved technology; architecture defines structure; agent instructions define working practices.
- Allow local layout, interaction, and component variations without changing the global design system. Propose updates to existing standards when an exception merits reuse; never silently alter global standards or create parallel standards unnecessarily.

Meaning: Product intent, design, technology, architecture and agent practice have separate responsibilities.

Rationale: This preserves human control while keeping requirements and implementation aligned.

Example: For a requested account-page change, implement only the agreed delta, maintain its current-state requirements, and run tests only when authorized.

Authority and modification: Current project operating instructions, presented as an example only; canonical SHAPE status pending owner confirmation. Confirm change authority with the repository owner. Prompts can authorize implementation; current-state requirements remain mandatory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/SHAPE.md · L32–L36 · 2026-10-15 · SHA-256: 7ab36352fe168076ee5592b1bc45a041fa3e04a9cbaf491d1f1ba97a84655b6e

Verbatim source in English:

## 6. Respect enterprise governance and reuse

- Work only in approved execution environments with technically enforced identities, permissions, and tool boundaries. Respect security, privacy, compliance, dependency, and data-handling restrictions; never bypass controls, expand privileges, or transfer data to unapproved services. Human approval alone cannot waive enforced restrictions.
- Reuse approved components, utilities, styles, libraries, and architectural patterns; follow repository conventions. Avoid duplicate implementations, unapproved dependencies, and unnecessary frameworks or abstractions. Explain and seek approval for justified exceptions.

Meaning: Respect enforced security boundaries and reuse approved solutions.

Rationale: This preserves human control while keeping requirements and implementation aligned.

Example: For a requested account-page change, implement only the agreed delta, maintain its current-state requirements, and run tests only when authorized.

Authority and modification: Current project operating instructions, presented as an example only; canonical SHAPE status pending owner confirmation. Confirm change authority with the repository owner. Prompts can authorize implementation; current-state requirements remain mandatory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/SHAPE.md · L37–L48 · 2026-10-15 · SHA-256: 7ab36352fe168076ee5592b1bc45a041fa3e04a9cbaf491d1f1ba97a84655b6e

Verbatim source in English:

## 7. Maintain current-state specifications

SHAPE separates optional **human-authored change specifications** from mandatory, **agent-maintained current-state specifications**.

- Human instructions may arrive as files, prompts, or conversations. Preserve original human-authored specification files unless explicitly authorized to edit them; Git records changes to files revised in place.
- Maintain a **comprehensive, consolidated, testable description of all implemented functionality**, no matter how each change was requested. Use the project's designated location (default: `specifications/current/`) and maintain a lightweight index.
- Organize into cohesive, manageable files by natural product boundaries: pages or shared features for websites; features, domains, workflows, or services for more complex systems. Split large files as needed.
- Describe required observable behavior, functional requirements, business rules, constraints, and acceptance criteria. Keep descriptions clear, implementation-independent, and sufficient for acceptance and regression testing. Reference shared design and technical standards rather than duplicating them.
- For **every implementation request**: examine the affected implementation and current specifications; identify the intended delta; preserve requirements not explicitly or unambiguously superseded; resolve material conflicts with a human; implement the smallest responsible change; create or update only affected current-state specifications; and identify affected tests.
- Keep current-state specifications aligned with **intended requirements**, not merely whatever code happens to do. Flag incomplete, ambiguous, or unverified requirements. Update specs alongside related implementation and Git commits.
- Current-state specifications describe the latest required behavior, **not human approval**. Human acceptance remains separate.

Meaning: Maintain comprehensive current-state requirements for every implemented capability, regardless of request format.

Rationale: This preserves human control while keeping requirements and implementation aligned.

Example: For a requested account-page change, implement only the agreed delta, maintain its current-state requirements, and run tests only when authorized.

Authority and modification: Current project operating instructions, presented as an example only; canonical SHAPE status pending owner confirmation. Confirm change authority with the repository owner. Prompts can authorize implementation; current-state requirements remain mandatory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/SHAPE.md · L49–L54 · 2026-10-15 · SHA-256: 7ab36352fe168076ee5592b1bc45a041fa3e04a9cbaf491d1f1ba97a84655b6e

Verbatim source in English:

## 8. Maintain specification-driven tests and protect regressions

- Derive and maintain acceptance and regression tests from current-state specifications and their criteria, whether requirements originated in formal files or informal instructions. Verify expected user-observable outcomes, not just the implementation's current behavior.
- For each change, identify affected behavior, components, and tests; maintain proportional coverage and reusable tests. Add, adjust, or retire tests when requirements legitimately change. Preserve existing coverage and do not weaken tests or expected outcomes to hide a defect. Explain any removed or changed test.
- Protect previously approved functionality. Material changes to it require renewed verification and, where applicable, human approval; unaffected approvals remain valid.

Meaning: Derive proportional regression and acceptance tests from intended requirements.

Rationale: This preserves human control while keeping requirements and implementation aligned.

Example: For a requested account-page change, implement only the agreed delta, maintain its current-state requirements, and run tests only when authorized.

Authority and modification: Current project operating instructions, presented as an example only; canonical SHAPE status pending owner confirmation. Confirm change authority with the repository owner. Prompts can authorize implementation; current-state requirements remain mandatory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/SHAPE.md · L55–L61 · 2026-10-15 · SHA-256: 7ab36352fe168076ee5592b1bc45a041fa3e04a9cbaf491d1f1ba97a84655b6e

Verbatim source in English:

### Human-controlled test execution

- **Execute tests only when a human explicitly initiates or authorizes them.** This includes unit, functional, browser, visual, regression, and full-suite runs, including agent-managed automated workflows.
- Agents may inspect, create, update, and prepare tests, perform static code inspection/reasoning, and recommend test scope, purpose, and likely duration without separate permission.
- A human may authorize a specific test, selected tests, or a suite. Authorization covers **only that execution scope**, not unrelated or future runs.
- After authorized execution, report passes, failures, skips, and unverified requirements. If tests were not run or could not run, report verification pending; never claim untested work is verified. Passing tests is not product acceptance.

Meaning: Execute tests only within explicit human authorization; report actual outcomes and gaps.

Rationale: This preserves human control while keeping requirements and implementation aligned.

Example: For a requested account-page change, implement only the agreed delta, maintain its current-state requirements, and run tests only when authorized.

Authority and modification: Current project operating instructions, presented as an example only; canonical SHAPE status pending owner confirmation. Confirm change authority with the repository owner. Prompts can authorize implementation; current-state requirements remain mandatory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/SHAPE.md · L62–L65 · 2026-10-15 · SHA-256: 7ab36352fe168076ee5592b1bc45a041fa3e04a9cbaf491d1f1ba97a84655b6e

Verbatim source in English:

## 9. Make work accountable

After each implementation, concisely report **what changed**, **the originating instruction/specification and affected current-state specifications**, **tests created or updated**, **what was actually tested**, **what remains unverified**, and **what requires human review**. Disclose meaningful deviations, discovered unintended effects, and incomplete work. Never represent proposed work as complete or agent verification as human approval.

Meaning: Report changes, sources, current-state specifications, tests and remaining human review.

Rationale: This preserves human control while keeping requirements and implementation aligned.

Example: For a requested account-page change, implement only the agreed delta, maintain its current-state requirements, and run tests only when authorized.

Authority and modification: Current project operating instructions, presented as an example only; canonical SHAPE status pending owner confirmation. Confirm change authority with the repository owner. Prompts can authorize implementation; current-state requirements remain mandatory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/SHAPE.md · L66–L70 · 2026-10-15 · SHA-256: 7ab36352fe168076ee5592b1bc45a041fa3e04a9cbaf491d1f1ba97a84655b6e

Verbatim source in English:

## Business context and objectives

- Projects should provide `OBJECTIVES.md` describing purpose, goals, audience, and desired outcomes. It is **non-authoritative context**, intended to improve agent judgment, not a source of mandatory requirements or permission to change scope.
- Use objectives to choose among otherwise valid alternatives; never let them override human requests, specifications, or governing instructions.

Meaning: Objectives provide non-authoritative context and cannot override requirements.

Rationale: This preserves human control while keeping requirements and implementation aligned.

Example: For a requested account-page change, implement only the agreed delta, maintain its current-state requirements, and run tests only when authorized.

Authority and modification: Current project operating instructions, presented as an example only; canonical SHAPE status pending owner confirmation. Confirm change authority with the repository owner. Prompts can authorize implementation; current-state requirements remain mandatory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot

agent_instructions/SHAPE.md · L71–L75 · 2026-10-15 · SHA-256: 7ab36352fe168076ee5592b1bc45a041fa3e04a9cbaf491d1f1ba97a84655b6e

Verbatim source in English:

## Application in a project

The project's `AGENTS.md` or equivalent entry point must direct agents to follow `SHAPE.md`. Other instruction and reference files provide project-specific context and constraints without replacing these principles.

**Intent:** Develop at the speed of thought while preserving human control, approved behavior, engineering discipline, spec-driven verification, and Git traceability.

Meaning: The project entry point discovers core principles and project-specific constraints.

Rationale: This preserves human control while keeping requirements and implementation aligned.

Example: For a requested account-page change, implement only the agreed delta, maintain its current-state requirements, and run tests only when authorized.

Authority and modification: Current project operating instructions, presented as an example only; canonical SHAPE status pending owner confirmation. Confirm change authority with the repository owner. Prompts can authorize implementation; current-state requirements remain mandatory.

Related material: Repository walkthrough · Specification practice · Download actual snapshot