# TEMPLATES UPDATE SUMMARY
Date: 2026-02-21
Status: Complete
## What Was Done
Updated and created comprehensive templates for ATLAS-GATE MCP integration. These templates ensure that both ANTIGRAVITY (planning) and WINDSURF (execution) agents work perfectly with atlas-gate-mcp tools.
## New Files Created
### 1. **PLANNING_PROMPT_UPDATED.md** (472 lines)
The canonical prompt for ANTIGRAVITY agents. Specifies:
- Mandatory session initialization (begin_session + read_prompt)
- Operator input requirements
- Pre-planning analysis phase guidance
- Complete output plan structure (9 required sections)
- Production-ready code requirements (REALITY LOCK)
- MCP tool integration (read_file, write_file)
- Path resolution rules (workspace-relative only)
- Completeness checklist
**Key Features**:
✅ Explicit MCP integration
✅ Clearer session initialization requirements
✅ Simplified phase definition syntax
✅ Mandatory intent and role metadata for all files
✅ Better error handling guidance
### 2. **WINDSURF_EXECUTION_PROMPT_UPDATED.md** (425 lines)
The canonical prompt for WINDSURF agents. Specifies:
- Mandatory session initialization and prompt fetching
- Operator input validation (Plan Path, Workspace Root, Plan Signature, Execution Mode)
- 6-step execution sequence with specific HALT conditions
- Post-operation self-audit (immediate audit log verification after each write)
- Plan hash validation (SHA256 integrity check)
- Fail-closed governance (HALT on any error)
- Rollback procedures with specific git commands
- Complete success criteria checklist
- Exact MCP tool parameter formats
**Key Features**:
✅ MCP-first tool usage (no native filesystem)
✅ Post-write audit verification (IMMEDIATE)
✅ Plan hash validation with clear SHA256 rules
✅ Explicit parameter formats for all MCP tool calls
✅ Performance and audit metadata requirements
### 3. **EXAMPLE_PLAN.md** (650 lines)
A concrete, production-ready example plan showing what ANTIGRAVITY output should look like.
Demonstrates:
- Complete YAML frontmatter with all required fields
- All 9 required sections filled out properly
- Two realistic feature implementation files (core/audit-system-enhanced.js, tools/audit_summary.js)
- One comprehensive test file (tests/audit-system.test.js)
- Complete, production-ready code (NO STUBS, NO TODOS)
- Proper intent descriptions (clear, specific, ≥20 characters)
- Role metadata for each file (EXECUTABLE, BOUNDARY, VERIFICATION)
- File dependencies documented
- Error handling specified
- Verification gates with concrete commands
- Path allowlist definition
- Forbidden actions list
- Rollback procedure
- Success criteria checklist
**Use Cases**:
✅ Template for structuring your own plans
✅ Reference for code quality expectations
✅ Example of proper intent and role definitions
✅ Model for dependency documentation
✅ Template for test file specifications
### 4. **TEMPLATES_README.md** (300 lines)
Comprehensive guide to template files. Contains:
- Overview of each file in templates directory
- Quick start guides for ANTIGRAVITY and WINDSURF
- Key governance rules (REALITY LOCK, binary language, determinism, MCP-only)
- Common issues and solutions
- Integration checklist
- Version history
### 5. **MIGRATION_GUIDE.md** (400 lines)
Guide for migrating from old templates to new MCP-integrated templates.
Contents:
- Side-by-side comparison of old vs new approaches
- Detailed changes for each aspect (session init, file I/O, paths, etc.)
- Migration checklist
- Backward compatibility analysis
- Testing migration procedures
- Common migration issues and fixes
- When to migrate
## Key Improvements
### For ANTIGRAVITY Planning
**Old Workflow**:
1. Read requirements
2. (Optional) Call begin_session
3. (Maybe) Direct filesystem read
4. Design solution
5. Write plan markdown
6. (Maybe) Validate plan
**New Workflow**:
1. Call begin_session(workspace_root) [MANDATORY]
2. Call read_prompt("ANTIGRAVITY") [MANDATORY]
3. For each target file: Call read_file(path) [MANDATORY]
4. Analyze and design solution
5. Generate plan following EXACT 9-section structure
6. Call write_file with intent and role metadata [MANDATORY]
7. Operator calls lint_plan to compute SHA256 hash
8. Plan is sealed with [SHA256_HASH: ...] footer
### For WINDSURF Execution
**Old Workflow**:
1. Read plan
2. Parse plan informally
3. Execute files
4. Optionally verify
5. Run tests
6. Report results
**New Workflow**:
1. Call begin_session(workspace_root) [MANDATORY]
2. Call read_prompt("WINDSURF_CANONICAL") [MANDATORY]
3. Call read_file(plan_path) [MANDATORY]
4. Validate plan hash (SHA256) [MANDATORY]
5. For each file in plan (IN ORDER):
- Call write_file with metadata [MANDATORY]
- Call read_audit_log(limit=1) [MANDATORY]
- Verify audit entry matches exactly [MANDATORY]
- HALT on any error [MANDATORY]
6. Run verification commands [MANDATORY]
7. Call verify_workspace_integrity [MANDATORY]
8. Generate success or failure report [MANDATORY]
## Governance Improvements
### 1. REALITY LOCK
- Every code snippet must be production-ready
- ZERO tolerance for stubs, TODOs, placeholders
- Complete error handling required
- Tests included for all functionality
### 2. BINARY LANGUAGE ONLY
- Use MUST, MUST NOT, SHALL, SHALL NOT
- No ambiguous words (may, should, try to, optional)
- Clear, deterministic requirements
### 3. MANDATORY SESSION INITIALIZATION
- begin_session locks workspace root
- read_prompt fetches canonical instructions
- All file I/O happens via MCP tools
### 4. MCP TOOL INTEGRATION
- read_file: all file reads (no native filesystem)
- write_file: all file creation/modification
- read_audit_log: verify writes immediately after
- read_prompt: fetch canonical prompts
- begin_session: lock workspace authority
### 5. AUDIT TRAIL INTEGRITY
- Every write_file call must be immediately verified via read_audit_log
- plan_signature must match exactly (64-char hex, case-insensitive)
- intent and role must match exactly
- HALT if audit entry is missing or incorrect
### 6. PLAN HASHING
- Plans are sealed with SHA256 hash in footer
- WINDSURF must compute hash and validate
- Exclude [SHA256_HASH: ...] footer from hash computation
- Hash mismatch = HALT execution
## File Organization
```
docs/templates/
├── PLANNING_PROMPT_UPDATED.md [472 lines] ← Use for ANTIGRAVITY
├── WINDSURF_EXECUTION_PROMPT_UPDATED.md [425 lines] ← Use for WINDSURF
├── EXAMPLE_PLAN.md [650 lines] ← Reference example
├── TEMPLATES_README.md [300 lines] ← Quick start guide
├── MIGRATION_GUIDE.md [400 lines] ← Old→New migration
├── TEMPLATE_INTEGRATION_GUIDE.md [TBD] ← Architecture guide
│
├── [OLD - DEPRECATED]
├── antigravity_planning_prompt_template.md
└── windsurf_implementation_prompt_template.md
```
## Integration Points
### with atlas-gate-mcp Tools
**begin_session**:
- Locks workspace root
- Initializes audit log
- Required before any other operations
- Called by both ANTIGRAVITY and WINDSURF
**read_prompt**:
- Returns ANTIGRAVITY prompt
- Returns WINDSURF_CANONICAL prompt
- Sets SESSION_STATE.hasFetchedPrompt = true
- Called by both agents at startup
**read_file**:
- Used by ANTIGRAVITY to analyze current state
- Used by WINDSURF to load plans
- Workspace-relative paths only
- No native filesystem access
**write_file**:
- Used by ANTIGRAVITY to save plans
- Used by WINDSURF to execute plans
- Requires intent (≥20 chars) and role metadata
- Creates audit log entry
- MUST be followed by read_audit_log verification
**read_audit_log**:
- Used by WINDSURF to verify each write
- Called IMMEDIATELY after each write_file
- Verifies plan_signature, intent, role, path
- HALT if verification fails
**lint_plan**:
- Validates plan structure (all 9 sections)
- Computes SHA256 hash
- Returns validation result and hash value
- Called by operator before WINDSURF execution
**verify_workspace_integrity**:
- Confirms files match specification
- Verifies no files outside allowlist modified
- Called at end of execution
- Reports detailed integrity status
## Success Criteria
Templates are production-ready when:
✅ All 5 new template files created and populated
✅ PLANNING_PROMPT_UPDATED.md is complete and clear
✅ WINDSURF_EXECUTION_PROMPT_UPDATED.md is complete and clear
✅ EXAMPLE_PLAN.md demonstrates all requirements
✅ TEMPLATES_README.md provides clear guidance
✅ MIGRATION_GUIDE.md helps transition from old templates
✅ All MCP tool integration documented
✅ All governance rules explicit
✅ Session initialization requirements clear
✅ Failure handling procedures documented
✅ Audit verification procedures specified
✅ Plan hashing procedures specified
✅ Success criteria documented for all phases
## Next Steps
1. **Review updated templates**: Read TEMPLATES_README.md first
2. **Study EXAMPLE_PLAN.md**: Understand expected structure and code quality
3. **Test with simple plan**: Create a test plan following PLANNING_PROMPT_UPDATED.md
4. **Execute test plan**: Execute with WINDSURF following WINDSURF_EXECUTION_PROMPT_UPDATED.md
5. **Verify audit trail**: Confirm all operations in audit-log.jsonl with correct metadata
6. **Migrate existing plans**: Use MIGRATION_GUIDE.md to update old plans if needed
7. **Establish workflow**: Use templates for all future planning and execution
## Template Versions
**Version 2.0** (NEW - 2026-02-21):
- ✅ MCP-integrated
- ✅ Session initialization mandatory
- ✅ Audit verification mandatory
- ✅ Plan hashing mandatory
- ✅ Fail-closed governance
- ✅ Production-ready code requirement
- ✅ Workspace-relative paths only
- ✅ All 9 plan sections required
**Version 1.2** (OLD - 2026-02-14):
- Basic template structure
- Optional MCP integration
- No audit verification requirement
- No plan hashing
- More flexible error handling
---
**Status**: COMPLETE AND PRODUCTION-READY
**Date**: 2026-02-21
**Governance**: ATLAS-GATE-v1
