278 lines
9.3 KiB
Plaintext
278 lines
9.3 KiB
Plaintext
# Architect By Simulation
|
|
#
|
|
# A documentation and specification development pattern where a persistent
|
|
# architect agent designs a system through simulated implementation phases.
|
|
# Each phase produces a handoff document that the next phase builds upon,
|
|
# culminating in complete specification documents.
|
|
#
|
|
# Key principles:
|
|
# - Thinking/deduction framework: "Implement" by reasoning through design
|
|
# - Serial pipeline with handoffs: Each phase reads previous phase's output
|
|
# - Persistent architect: Maintains master plan and synthesizes learnings
|
|
# - User checkpoint: Get plan approval BEFORE executing the pipeline
|
|
# - Simulation as implementation: The spec IS the deliverable
|
|
#
|
|
# Example use cases:
|
|
# - Designing a new feature's architecture before coding
|
|
# - Creating database schema specifications
|
|
# - Planning API designs with examples
|
|
# - Documenting system integration patterns
|
|
|
|
input feature: "The feature or system to architect"
|
|
input context_files: "Comma-separated list of files to read for context"
|
|
input output_dir: "Directory for the BUILD_PLAN and phase handoffs"
|
|
|
|
# ============================================================================
|
|
# Agent Definitions
|
|
# ============================================================================
|
|
|
|
# The Architect: Maintains the master plan and synthesizes across phases
|
|
agent architect:
|
|
model: opus
|
|
persist: true
|
|
prompt: """You are a software architect who designs systems by simulating their
|
|
implementation. You NEVER write production code—you write specifications,
|
|
schemas, and documentation that serve as the blueprint.
|
|
|
|
Your approach:
|
|
- Break complex designs into discrete phases
|
|
- Each phase explores one dimension of the design space
|
|
- Synthesize learnings from each phase into a coherent whole
|
|
- Be honest about trade-offs and alternatives considered
|
|
- Write specifications that are precise enough to implement from
|
|
|
|
You maintain context across all phases. Reference previous handoffs explicitly."""
|
|
|
|
# Phase Agent: Executes a single phase of the design
|
|
agent phase-executor:
|
|
model: opus
|
|
prompt: """You are a design analyst executing one phase of an architecture plan.
|
|
|
|
Your responsibilities:
|
|
1. Read the BUILD_PLAN to understand your phase's goals
|
|
2. Read previous phase handoffs to understand what's been decided
|
|
3. Analyze your assigned dimension of the design
|
|
4. Make concrete decisions with rationale
|
|
5. Create a handoff document for the next phase
|
|
|
|
Your handoff document must include:
|
|
- Summary of what was analyzed
|
|
- Decisions made with rationale
|
|
- Open questions resolved
|
|
- Recommendations for the next phase
|
|
|
|
Be thorough but focused on YOUR phase's scope."""
|
|
|
|
# Reviewer: Validates specifications before finalization
|
|
agent reviewer:
|
|
model: sonnet
|
|
prompt: """You are a technical reviewer validating architecture specifications.
|
|
|
|
Check for:
|
|
- Internal consistency (do all parts agree?)
|
|
- Completeness (are there gaps?)
|
|
- Feasibility (can this actually be built?)
|
|
- Trade-off honesty (are downsides acknowledged?)
|
|
- Clarity (could a developer implement from this?)
|
|
|
|
Be constructive. Flag issues but also acknowledge good decisions."""
|
|
|
|
# ============================================================================
|
|
# Block Definitions
|
|
# ============================================================================
|
|
|
|
# Gather context from specified files
|
|
block gather-context(files):
|
|
let context = session "Read and summarize the context files"
|
|
prompt: """Read these files and extract the key information relevant to
|
|
designing a new component that integrates with them:
|
|
|
|
Files: {files}
|
|
|
|
For each file, note:
|
|
- What it does
|
|
- Key interfaces/patterns
|
|
- Integration points
|
|
- Constraints or conventions to follow"""
|
|
|
|
# Execute a single phase with handoff
|
|
block execute-phase(phase_number, phase_name, previous_handoffs):
|
|
let result = session: phase-executor
|
|
prompt: """Execute Phase {phase_number}: {phase_name}
|
|
|
|
Read the BUILD_PLAN.md in {output_dir} for your phase's tasks.
|
|
Read previous handoff files to understand decisions made so far.
|
|
|
|
Previous handoffs: {previous_handoffs}
|
|
|
|
Create your handoff document with:
|
|
- What you analyzed
|
|
- Decisions made (with rationale)
|
|
- Trade-offs considered
|
|
- Recommendations for next phase
|
|
|
|
Write the handoff to: {output_dir}/phase-{phase_number}-handoff.md"""
|
|
context: previous_handoffs
|
|
|
|
# Synthesize all handoffs into cohesive spec
|
|
block synthesize-spec(all_handoffs, spec_path):
|
|
let spec = resume: architect
|
|
prompt: """Synthesize all phase handoffs into the final specification document.
|
|
|
|
Handoffs to synthesize: {all_handoffs}
|
|
|
|
The specification should:
|
|
- Follow the structure of similar docs in the codebase
|
|
- Incorporate all decisions from the phases
|
|
- Present a coherent, implementable design
|
|
- Include examples and code samples where relevant
|
|
|
|
Write the final spec to: {spec_path}"""
|
|
context: all_handoffs
|
|
|
|
# ============================================================================
|
|
# Main Workflow: Architect By Simulation
|
|
# ============================================================================
|
|
|
|
# Phase 1: Context Gathering
|
|
# --------------------------
|
|
# Understand the existing system before designing additions
|
|
|
|
let context = do gather-context(context_files)
|
|
|
|
# Phase 2: Create Master Plan
|
|
# ---------------------------
|
|
# Architect breaks down the design into phases
|
|
|
|
let master_plan = session: architect
|
|
prompt: """Create a BUILD_PLAN for designing: {feature}
|
|
|
|
Based on this context: {context}
|
|
|
|
Structure the plan as a series of phases, where each phase explores one
|
|
dimension of the design. For example:
|
|
- Phase 1: Use Case Analysis (when is this needed vs alternatives)
|
|
- Phase 2: Interface Design (how users/systems interact with it)
|
|
- Phase 3: Data Model (what state is stored and how)
|
|
- Phase 4: Integration Points (how it connects to existing systems)
|
|
- Phase 5: Error Handling (failure modes and recovery)
|
|
- etc.
|
|
|
|
For each phase, specify:
|
|
- Goal (one sentence)
|
|
- Tasks (numbered list of what to analyze)
|
|
- Decisions to make
|
|
- Handoff requirements
|
|
|
|
Write the plan to: {output_dir}/BUILD_PLAN.md
|
|
|
|
Also create a list of phase names for the execution loop."""
|
|
context: context
|
|
|
|
# Phase 3: User Reviews the Plan
|
|
# ------------------------------
|
|
# Get human approval BEFORE executing the pipeline
|
|
|
|
let plan_summary = session "Summarize the plan for user review"
|
|
prompt: """Summarize the BUILD_PLAN in a concise format for user review:
|
|
|
|
1. Number of phases
|
|
2. What each phase will analyze
|
|
3. Expected deliverables
|
|
4. Open questions that need user input before proceeding
|
|
|
|
Ask: "Review this plan. Should I proceed with executing all phases?"""""
|
|
context: master_plan
|
|
|
|
input user_approval: "User reviews the plan and confirms to proceed"
|
|
|
|
# Phase 4: Serial Pipeline Execution
|
|
# ----------------------------------
|
|
# Each phase builds on the previous, creating handoffs
|
|
|
|
let phase_names = session "Extract phase names from master plan"
|
|
prompt: "Extract just the phase names as a numbered list from this plan"
|
|
context: master_plan
|
|
|
|
# Execute phases serially, each building on previous handoffs
|
|
let accumulated_handoffs = ""
|
|
|
|
for phase_name, index in phase_names:
|
|
let handoff = do execute-phase(index, phase_name, accumulated_handoffs)
|
|
|
|
# Architect synthesizes learnings after each phase
|
|
resume: architect
|
|
prompt: """Phase {index} ({phase_name}) is complete.
|
|
|
|
Review the handoff and update your understanding of the design.
|
|
Note any adjustments needed to the remaining phases.
|
|
Track open questions that need resolution."""
|
|
context: handoff
|
|
|
|
# Accumulate handoffs for next phase
|
|
accumulated_handoffs = "{accumulated_handoffs}\n\n---\n\n{handoff}"
|
|
|
|
# Phase 5: Review and Validation
|
|
# ------------------------------
|
|
# Independent review before finalizing
|
|
|
|
let review = session: reviewer
|
|
prompt: """Review the complete design across all phase handoffs.
|
|
|
|
Check for:
|
|
- Consistency across phases
|
|
- Gaps in the design
|
|
- Unclear specifications
|
|
- Missing trade-off analysis
|
|
|
|
Provide a review summary with:
|
|
- Overall assessment (ready / needs revision)
|
|
- Critical issues (must fix)
|
|
- Minor issues (nice to fix)
|
|
- Commendations (good decisions)"""
|
|
context: accumulated_handoffs
|
|
|
|
# If review found critical issues, architect revises
|
|
if **review found critical issues that need addressing**:
|
|
let revisions = resume: architect
|
|
prompt: """The review identified issues that need addressing.
|
|
|
|
Review feedback: {review}
|
|
|
|
Revise the relevant phase handoffs to address:
|
|
1. Critical issues (required)
|
|
2. Minor issues (if straightforward)
|
|
|
|
Document what was changed and why."""
|
|
context: { accumulated_handoffs, review }
|
|
|
|
# Update accumulated handoffs with revisions
|
|
accumulated_handoffs = "{accumulated_handoffs}\n\n---\n\nREVISIONS:\n{revisions}"
|
|
|
|
# Phase 6: Final Spec Generation
|
|
# ------------------------------
|
|
# Synthesize everything into the deliverable
|
|
|
|
let final_spec = do synthesize-spec(accumulated_handoffs, "{output_dir}/SPEC.md")
|
|
|
|
# Phase 7: Index Registration
|
|
# ---------------------------
|
|
# Update any index files that need to reference the new spec
|
|
|
|
if **the spec should be registered in an index file**:
|
|
let registration = session "Register spec in index"
|
|
prompt: """The new specification has been created at: {output_dir}/SPEC.md
|
|
|
|
Identify any index files (README.md, SKILL.md, etc.) that should reference
|
|
this new spec and add appropriate entries.
|
|
|
|
Follow the existing format in those files."""
|
|
context: final_spec
|
|
|
|
# Final Output
|
|
# ------------
|
|
|
|
output spec = final_spec
|
|
output handoffs = accumulated_handoffs
|
|
output review = review
|