Reusable starting points, not additional bureaucracy
These templates illustrate a consistent way to record important decisions and results in the SHAPE Framework. They are deliberately short. Teams should adapt them to product complexity and enterprise policy rather than filling every heading with repetitive text.
The framework does not prescribe a fixed set of named Markdown documents in agent_instructions/. The examples below show possible artifacts and their responsibilities. Feature specifications remain separate from standing instructions.
Template A. Root `AGENTS.md`
A root entry point should do one job: direct the coding agent to the project's standing instruction documents. It should not require a maintained list of individual filenames.
# AGENTS.md
Read and observe all Markdown (`.md`) files in `agent_instructions/` before starting work and throughout implementation.
The root file can remain this simple even when projects add more standing instructions.
Template B. Self-describing instruction document
Every Markdown file inside agent_instructions/ should begin by declaring what it covers. This example is intentionally generic; its filename is not mandated.
# [Purpose: explain what this instruction document governs]
## Applicability
- [Which project or activity these instructions cover]
## Rules
- [Mandatory, actionable rule]
- [Another rule, if necessary]
## Approval or escalation
- [Which decisions need owner approval]
## Related context
- [Optional references to other authoritative material]
This template can support project objectives, architecture constraints, design guidance, approved dependencies, or another subject. Do not combine unrelated concerns merely because they are all written in Markdown. Follow the organization's document approval rules.
Template C. Project objectives
A project objectives document explains why the product exists and what it should achieve. Its location and name may be chosen by the project as part of its standing context.
# Product objectives and scope for [Product Name]
## Problem
[What problem exists today and for whom?]
## Intended outcomes
- [Observable outcome]
- [Another outcome, if relevant]
## Users and stakeholders
- [Actor or stakeholder and their interest]
## Initial scope
- [Included capability]
## Exclusions
- [Explicitly excluded capability]
## Constraints and dependencies
- [Existing policies, systems, limitations, or approvals]
## Open business decisions
- [Question, decision owner, and current status]
Template D. Feature specification
Store feature specifications in the project's specs/ area. Use a stable identifier and keep the document updated as the behavior evolves.
# SPEC-[ID]: [Feature name]
## Purpose
[User/business outcome and why the feature exists]
## Scope
[Behavior included and important exclusions]
## Actors and permissions
[Who may see, initiate, change, or decide]
## Preconditions
[Required state, data, or policy assumptions]
## Expected behavior
1. [Observable behavior]
2. [Observable behavior]
## Business rules
- [Rule and its consequences]
## Exceptions and failures
- [What happens on invalid input, denied access, or failed dependency]
## Acceptance conditions
- AC-01: [Observable, verifiable condition]
- AC-02: [Observable, verifiable condition]
## Dependencies and references
- [Other specifications or approved standards]
## Unresolved decisions
- [Open issue and decision owner, if any]
A specification does not need to prescribe source-code structure or a particular UI layout unless such a constraint is itself an approved product requirement.
Template E. Architect review record
# Technical review: [Product / Change]
## Review stage
[Initial Cycle 1 / Final Cycle 1 / Required Cycle 2]
## Scope
[What was reviewed and relevant specifications or changes]
## Findings
| ID | Significance | Finding and consequence | Required action | Owner | Status |
|----|--------------|-------------------------|-----------------|-------|--------|
| R-01 | [Level] | [Problem] | [Correction or decision] | [Owner] | [Open/Resolved] |
## Outstanding risks or exceptions
[Material items and their approved disposition]
## Technical conclusion
[Ready / Not ready / Conditional under policy, with reviewer]
The record is proportionate to the change. It documents important engineering judgment without making an architect review equivalent to business acceptance.
Template F. Spec-Based Testing result
# Independent specification verification: [Product / Change]
## Scope
[Specifications and behaviors in scope]
## Verification independence
[How the verification context was separated from implementation]
## Environment and limits
[Authorized test context, representative data, blocked capabilities]
## Results
| Requirement | Check performed | Expected | Observed | Status | Evidence/reference |
|-------------|-----------------|----------|----------|--------|--------------------|
| SPEC-X / AC-01 | [Check] | [Expected] | [Observed] | Pass / Fail / Blocked / Needs clarification | [Reference] |
## Outstanding findings
[Failures, blockers, ambiguities and their owners]
## Retest outcome
[What changed and what was retested]
## Summary
[Verified scope and remaining uncertainty, without overstating coverage]
This is an example reporting structure. Existing enterprise test-management procedures may provide equivalent records.
Template G. Lightweight retrospective
# Development retrospective: [Product / Cycle]
## What worked
- [Specific effective practice]
## What caused repeated friction
- [Specific problem and effect]
## Agreed improvements
| Change | Local or shared | Responsible owner | Approval needed? |
|--------|-----------------|-------------------|------------------|
| [Action] | [Scope] | [Owner] | [Yes/No] |
## No-action decisions
[Optional explanation for issues intentionally left unchanged]
A retrospective need not produce new actions if existing practices are working. Changes to shared enterprise materials follow their established governance.
Using templates responsibly
Replace bracketed prompts with project-specific facts and decisions. Remove irrelevant headings rather than manufacturing content. Maintain specification consistency with real product behavior. Do not copy example permission rules or implied security mechanisms into a production project without applying its policies.