Add design phase + 3D visualization + orchestration improvements

This commit is contained in:
2026-05-31 00:29:10 -04:00
parent 72ae07c310
commit d235c12ab0
8 changed files with 642 additions and 2 deletions
+4 -1
View File
@@ -1,9 +1,12 @@
# AGENT.md
IF task type = research → load prompts/research.md + RULES.md
IF task type = implement → load prompts/implement.md + SPEC.md + CONTRACT.md
IF task type = design → load prompts/design.md + SPEC.md
IF task type = implement → load prompts/implement.md + SPEC.md + DESIGN.md + CONTRACT.md
IF task type = bug_find → load prompts/bug_finder.md + SPEC.md + code
IF task type = disprove → load prompts/disprover.md + SPEC.md + BUGS.md
IF task type = referee → load prompts/referee.md + SPEC.md + BUGS.md + DISPROVALS.md
IF task type = orchestrate → load prompts/orchestrate.md + project structure
IF task type = compaction → load prompts/compaction.md
Always start by reading this file to determine mode.
+8 -1
View File
@@ -33,13 +33,20 @@ Then run the onboarding prompt:
All work happens through prompts in `~/.agent-framework/prompts/`:
- Research → `prompts/research.md`
### Core Phases
- Research → `prompts/research.md` (produces SPEC.md)
- Design → `prompts/design.md` (produces DESIGN.md) — recommended for greenfield projects
- Implement → `prompts/implement.md`
### Quality Phases (Optional)
- Bug finding → `prompts/bug_finder.md`
- Disprove → `prompts/disprover.md`
- Referee → `prompts/referee.md`
### Other
- Onboarding → `prompts/onboarding.md`
- Compaction → `prompts/compaction.md`
- Orchestrate → `prompts/orchestrate.md`
See `ONBOARDING.md` for detailed drop-in vs from-scratch scenarios and the full philosophy.
+49
View File
@@ -0,0 +1,49 @@
You are in design mode.
Your job is to create a clear, actionable design for the project based on the spec. Do not write code.
## Read These Files
1. {project}/tasks/{task-name}/SPEC.md
2. {project}/.agent-framework/RULES.md
## Task
{task-description}
## Output
Produce a file called `DESIGN.md` at {project}/tasks/{task-name}/DESIGN.md containing:
### 1. Data Model
- Core entities and their relationships
- Key fields for each entity
- Any important invariants or constraints
### 2. Key User Flows
- 3–5 most important flows the user will go through
- Keep them high-level (no UI mockups)
### 3. Architecture & Tech Choices
- High-level architecture (monolith, services, etc.)
- Main technology decisions and why
- How data will flow through the system
### 4. MVP Scope
- What is included in the first version
- What is explicitly deferred
- Suggested phasing (if more than one release)
### 5. Risks & Unknowns
- Biggest technical or product risks
- Areas that need exploration or validation first
### 6. Non-Functional Requirements
- Performance, security, reliability, or scale considerations (if relevant)
When the design is complete, output "CONTRACT_MET" and stop.
## Rules
- Stay at the design level. Do not write code or detailed implementation steps.
- Be specific enough that implementation can proceed with clarity.
- If something is unclear, state the assumption and move on.
+43
View File
@@ -0,0 +1,43 @@
You are in orchestration mode.
Your job is to analyze the current state of the project and recommend the next logical phase. You do **not** run any phases yourself.
## Read These Files
1. {project}/.agent-framework/AGENT.md
2. {project}/.agent-framework/RULES.md
3. Any existing files under {project}/tasks/
## Task
{task-description}
## Analysis Rules
Examine the tasks/ directory and determine the state of each task folder using these signals:
- No SPEC.md → needs **research**
- Has SPEC.md but no IMPLEMENTATION.md → needs **implement**
- Has implementation but no BUG_REPORT.md → can optionally run **bug_find**
- Has BUG_REPORT.md but no DISPROVALS.md → can run **disprove**
- Has BUG_REPORT.md + DISPROVALS.md but no VERDICT.md → needs **referee**
- Has VERDICT.md with PASS → task is complete
## Output Format
For each task, output one of the following recommendations:
**Recommended next action:**
- Phase: research / implement / bug_find / disprove / referee
- Exact command to give the agent:
> "Research {task-description}"
> "Implement the {task-name} task"
> "Find bugs in the {task-name} task"
> "Disprove the bugs in the {task-name} task"
> "Review the {task-name} task"
If everything is complete, say so clearly.
Only recommend one phase at a time. Do not suggest running multiple phases in parallel.
When finished, output "ORCHESTRATION_COMPLETE".
+26
View File
@@ -0,0 +1,26 @@
# Session Starter Template
Copy and paste this at the very beginning of every new agent session (before giving your actual task).
---
Read the following files in order, then wait for my instructions:
1. ~/.agent-framework/AGENT.md (global framework router)
2. {project}/.agent-framework/AGENT.md (project-level router, if it exists)
3. {project}/.agent-framework/RULES.md (if it exists)
After reading these files, acknowledge with: "AGENT.md and RULES.md loaded. Ready."
---
## How to Use
1. Start a fresh session with your agent.
2. Paste the block above (replace `{project}` with the actual path).
3. Then give your real request, for example:
- "What should we do next on this project?"
- "Implement the fix-alert-test task"
- "Onboard this project to the agent framework"
This guarantees the agent always follows the routing rules in `AGENT.md`.
+11
View File
@@ -0,0 +1,11 @@
You are working inside the minimal agent framework.
At the very start of every session, you must:
1. Read ~/.agent-framework/AGENT.md (global router)
2. Read the current project's .agent-framework/AGENT.md (if it exists)
3. Read the current project's .agent-framework/RULES.md (if it exists)
After reading these files, respond with: "Framework context loaded. Ready for task."
Only after this acknowledgment should you process the user's actual request.
+285
View File
@@ -0,0 +1,285 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Agent Framework • 3D Sphere</title>
<script src="https://cdn.tailwindcss.com"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js"></script>
<style>
body { margin: 0; overflow: hidden; }
#canvas-container { width: 100%; height: 100vh; }
.label {
position: absolute;
color: #a1a1aa;
font-size: 11px;
pointer-events: none;
text-shadow: 0 1px 3px rgba(0,0,0,0.9);
font-family: ui-monospace, monospace;
}
</style>
</head>
<body class="bg-zinc-950 text-zinc-200">
<div class="absolute top-6 left-6 z-10">
<div>
<div class="text-2xl font-semibold tracking-tight">Agent Framework</div>
<div class="text-xs text-zinc-500">3D Phase Visualization</div>
</div>
</div>
<div id="canvas-container"></div>
<!-- Details Panel -->
<div class="absolute top-6 right-6 w-80 bg-zinc-900/90 backdrop-blur border border-zinc-800 rounded-3xl p-6 z-20 hidden" id="details-panel">
<div id="details-content"></div>
</div>
<div class="absolute bottom-6 left-6 text-[10px] text-zinc-500 z-10">
Drag to rotate • Scroll to zoom • Click nodes
</div>
<script>
const phaseData = {
"Research": { prompt: "prompts/research.md", outputs: "SPEC.md", description: "Explores requirements and produces a clear specification." },
"Design": { prompt: "prompts/design.md", outputs: "DESIGN.md", description: "Produces data models, flows, architecture, and risks." },
"Implement": { prompt: "prompts/implement.md", outputs: "Code + tests", description: "Builds the solution using SPEC.md and DESIGN.md." },
"Bug Find": { prompt: "prompts/bug_finder.md", outputs: "BUG_REPORT.md", description: "Adversarially discovers bugs and spec deviations." },
"Disprove": { prompt: "prompts/disprover.md", outputs: "DISPROVALS.md", description: "Attempts to disprove findings from the bug report." },
"Referee": { prompt: "prompts/referee.md", outputs: "VERDICT.md", description: "Judges implementation and compares Bug Finder vs Disprover." },
"Onboard": { prompt: "prompts/onboarding.md", outputs: "Framework files", description: "Initializes the agent framework in a project." },
"Orchestrate": { prompt: "prompts/orchestrate.md", outputs: "Recommendation", description: "Suggests the next logical phase based on state." },
"Compaction": { prompt: "prompts/compaction.md", outputs: "Clean rules", description: "Consolidates and deduplicates rules." }
};
const phases = Object.keys(phaseData);
let scene, camera, renderer;
let nodes = [];
let lines = [];
let raycaster, mouse;
function initThreeJS() {
const container = document.getElementById('canvas-container');
scene = new THREE.Scene();
camera = new THREE.PerspectiveCamera(60, window.innerWidth / window.innerHeight, 0.1, 1000);
renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
renderer.setSize(window.innerWidth, window.innerHeight);
container.appendChild(renderer.domElement);
// Sphere
const sphereGeometry = new THREE.SphereGeometry(2.4, 64, 64);
const sphereMaterial = new THREE.MeshPhongMaterial({
color: 0x18181b,
wireframe: true,
transparent: true,
opacity: 0.12
});
const sphere = new THREE.Mesh(sphereGeometry, sphereMaterial);
scene.add(sphere);
// Lighting
const ambientLight = new THREE.AmbientLight(0xffffff, 0.6);
scene.add(ambientLight);
const pointLight = new THREE.PointLight(0xffffff, 0.9);
pointLight.position.set(10, 10, 10);
scene.add(pointLight);
camera.position.z = 6.5;
raycaster = new THREE.Raycaster();
mouse = new THREE.Vector2();
// Create nodes + connections
createNodesOnSphere();
createConnections();
// Events
window.addEventListener('resize', onWindowResize);
container.addEventListener('click', onClick);
// Orbit controls (simple)
let isDragging = false;
let previousMouseX = 0, previousMouseY = 0;
container.addEventListener('mousedown', (e) => {
isDragging = true;
previousMouseX = e.clientX;
previousMouseY = e.clientY;
});
window.addEventListener('mouseup', () => isDragging = false);
container.addEventListener('mousemove', (e) => {
if (!isDragging) return;
const deltaMove = { x: e.clientX - previousMouseX, y: e.clientY - previousMouseY };
const deltaRotation = new THREE.Quaternion().setFromEuler(
new THREE.Euler(deltaMove.y * 0.004, deltaMove.x * 0.004, 0, 'XYZ')
);
sphere.quaternion.multiplyQuaternions(deltaRotation, sphere.quaternion);
nodes.forEach(n => n.position.applyQuaternion(deltaRotation));
lines.forEach(line => {
line.geometry.dispose();
const newGeo = new THREE.BufferGeometry().setFromPoints([
line.userData.from.position,
line.userData.to.position
]);
line.geometry = newGeo;
});
previousMouseX = e.clientX;
previousMouseY = e.clientY;
});
container.addEventListener('wheel', (e) => {
camera.position.z += e.deltaY * 0.008;
camera.position.z = Math.max(3.5, Math.min(11, camera.position.z));
});
animate();
}
function createNodesOnSphere() {
const radius = 2.4;
const nodeCount = phases.length;
phases.forEach((phase, i) => {
const phi = Math.acos(-1 + (2 * i) / nodeCount);
const theta = Math.sqrt(nodeCount * Math.PI) * phi;
const x = radius * Math.sin(phi) * Math.cos(theta);
const y = radius * Math.sin(phi) * Math.sin(theta);
const z = radius * Math.cos(phi);
const geometry = new THREE.SphereGeometry(0.11, 16, 16);
const material = new THREE.MeshPhongMaterial({
color: 0x3b82f6,
emissive: 0x1e40af
});
const nodeMesh = new THREE.Mesh(geometry, material);
nodeMesh.position.set(x, y, z);
nodeMesh.userData = { phase: phase };
scene.add(nodeMesh);
nodes.push(nodeMesh);
// Label
const label = document.createElement('div');
label.className = 'label';
label.textContent = phase;
document.getElementById('canvas-container').appendChild(label);
nodeMesh.userData.label = label;
});
}
function createConnections() {
const connections = [
["Research", "Design"],
["Design", "Implement"],
["Implement", "Bug Find"],
["Bug Find", "Disprove"],
["Disprove", "Referee"],
["Referee", "Implement"],
["Onboard", "Research"],
["Orchestrate", "Research"],
["Orchestrate", "Design"],
["Orchestrate", "Implement"],
["Orchestrate", "Bug Find"],
["Orchestrate", "Referee"],
["Compaction", "Orchestrate"]
];
const lineMaterial = new THREE.LineBasicMaterial({
color: 0x3f3f46,
transparent: true,
opacity: 0.6
});
connections.forEach(([fromName, toName]) => {
const fromNode = nodes.find(n => n.userData.phase === fromName);
const toNode = nodes.find(n => n.userData.phase === toName);
if (!fromNode || !toNode) return;
const geometry = new THREE.BufferGeometry().setFromPoints([
fromNode.position,
toNode.position
]);
const line = new THREE.Line(geometry, lineMaterial);
line.userData = { from: fromNode, to: toNode };
scene.add(line);
lines.push(line);
});
}
function onClick(event) {
const rect = renderer.domElement.getBoundingClientRect();
mouse.x = ((event.clientX - rect.left) / rect.width) * 2 - 1;
mouse.y = -((event.clientY - rect.top) / rect.height) * 2 + 1;
raycaster.setFromCamera(mouse, camera);
const intersects = raycaster.intersectObjects(nodes);
if (intersects.length > 0) {
const phase = intersects[0].object.userData.phase;
showDetails(phase);
}
}
function showDetails(phase) {
const panel = document.getElementById('details-panel');
const data = phaseData[phase];
panel.classList.remove('hidden');
panel.innerHTML = `
<div class="flex justify-between items-start mb-4">
<div>
<div class="text-xl font-semibold">${phase}</div>
<div class="text-xs text-blue-400 font-mono mt-1">${data.prompt}</div>
</div>
<button onclick="hideDetails()" class="text-zinc-500 hover:text-white text-xl">×</button>
</div>
<div class="text-sm leading-relaxed text-zinc-300">${data.description}</div>
<div class="mt-6">
<div class="text-xs uppercase tracking-wider text-zinc-500 mb-2">Outputs</div>
<div class="text-sm font-mono bg-zinc-950 px-4 py-2 rounded-2xl border border-zinc-800">${data.outputs}</div>
</div>
`;
}
function hideDetails() {
document.getElementById('details-panel').classList.add('hidden');
}
function onWindowResize() {
camera.aspect = window.innerWidth / window.innerHeight;
camera.updateProjectionMatrix();
renderer.setSize(window.innerWidth, window.innerHeight);
}
function animate() {
requestAnimationFrame(animate);
renderer.render(scene, camera);
// Update labels
nodes.forEach(node => {
if (node.userData.label) {
const vector = node.position.clone();
vector.project(camera);
const x = (vector.x * 0.5 + 0.5) * window.innerWidth;
const y = (-vector.y * 0.5 + 0.5) * window.innerHeight;
node.userData.label.style.left = `${x}px`;
node.userData.label.style.top = `${y}px`;
}
});
}
function init() {
initThreeJS();
}
window.onload = init;
</script>
</body>
</html>
+216
View File
@@ -0,0 +1,216 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Agent Framework • Routes</title>
<script src="https://cdn.tailwindcss.com"></script>
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<style>
.mermaid { font-family: ui-sans-serif, system-ui, sans-serif; }
.node { cursor: pointer; }
</style>
</head>
<body class="bg-zinc-950 text-zinc-200">
<div class="max-w-7xl mx-auto p-8">
<div class="flex items-center justify-between mb-8">
<div>
<h1 class="text-3xl font-semibold tracking-tight">Agent Framework</h1>
<p class="text-zinc-400 mt-1">Phase relationships and routing</p>
</div>
<div class="text-xs px-3 py-1.5 bg-zinc-900 rounded-full border border-zinc-800">~/.agent-framework</div>
</div>
<div class="grid grid-cols-1 lg:grid-cols-12 gap-6">
<!-- Graph -->
<div class="lg:col-span-8 bg-zinc-900 rounded-3xl p-8 border border-zinc-800">
<div class="flex items-center justify-between mb-6">
<div class="text-sm font-medium text-zinc-400">Phase Graph</div>
<div class="text-[10px] text-zinc-500">Click any node for details</div>
</div>
<div id="mermaid-diagram" class="overflow-auto"></div>
</div>
<!-- Details -->
<div class="lg:col-span-4 bg-zinc-900 rounded-3xl p-8 border border-zinc-800">
<div class="text-sm font-medium text-zinc-400 mb-4">Phase Details</div>
<div id="details-panel">
<div class="text-zinc-500 text-sm">Select a phase to view its prompt, outputs, and dependencies.</div>
</div>
</div>
</div>
</div>
<script>
const phaseData = {
"Research": {
prompt: "prompts/research.md",
outputs: "SPEC.md",
description: "Explores requirements and produces a clear specification.",
dependsOn: []
},
"Design": {
prompt: "prompts/design.md",
outputs: "DESIGN.md",
description: "Produces data models, user flows, architecture, MVP scope, and risks.",
dependsOn: ["SPEC.md"]
},
"Implement": {
prompt: "prompts/implement.md",
outputs: "Code + tests",
description: "Builds the solution using SPEC.md and DESIGN.md.",
dependsOn: ["SPEC.md", "DESIGN.md"]
},
"Bug Find": {
prompt: "prompts/bug_finder.md",
outputs: "BUG_REPORT.md",
description: "Adversarially discovers bugs and spec deviations.",
dependsOn: ["SPEC.md", "IMPLEMENTATION.md"]
},
"Disprove": {
prompt: "prompts/disprover.md",
outputs: "DISPROVALS.md",
description: "Attempts to disprove findings from the bug report.",
dependsOn: ["BUG_REPORT.md"]
},
"Referee": {
prompt: "prompts/referee.md",
outputs: "VERDICT.md",
description: "Judges implementation quality and compares Bug Finder vs Disprover.",
dependsOn: ["SPEC.md", "BUG_REPORT.md", "DISPROVALS.md"]
},
"Onboard": {
prompt: "prompts/onboarding.md",
outputs: "Framework files + report",
description: "Initializes the agent framework in a new or existing project.",
dependsOn: []
},
"Orchestrate": {
prompt: "prompts/orchestrate.md",
outputs: "Next phase recommendation",
description: "Analyzes current state and suggests the logical next phase.",
dependsOn: ["All task artifacts"]
},
"Compaction": {
prompt: "prompts/compaction.md",
outputs: "Consolidated rules",
description: "Cleans up and deduplicates rules and routing logic.",
dependsOn: ["RULES.md", "AGENT.md"]
}
};
const diagram = `
graph TD
Research --> Design
Design --> Implement
Implement --> BugFind[Bug Find]
BugFind --> Disprove
Disprove --> Referee
Referee -->|pass| Implement
Referee -->|fail| BugFind
Onboard --> Research
Orchestrate -.-> Research
Orchestrate -.-> Design
Orchestrate -.-> Implement
Orchestrate -.-> BugFind
Orchestrate -.-> Referee
Compaction -.-> Orchestrate
classDef core fill:#1e40af,stroke:#3b82f6,color:#fff
classDef quality fill:#854d0e,stroke:#ca8a04,color:#fff
classDef meta fill:#334155,stroke:#64748b,color:#fff
class Research,Design,Implement core
class BugFind,Disprove,Referee quality
class Onboard,Orchestrate,Compaction meta
`;
function renderDiagram() {
const container = document.getElementById('mermaid-diagram');
container.innerHTML = `<pre class="mermaid">${diagram}</pre>`;
mermaid.initialize({
startOnLoad: false,
theme: 'dark',
flowchart: { curve: 'basis', padding: 20 }
});
mermaid.run().then(() => {
attachClickHandlers();
});
}
function attachClickHandlers() {
const nodes = document.querySelectorAll('#mermaid-diagram .node');
nodes.forEach(node => {
let label = node.textContent.trim();
// Handle Mermaid's internal node IDs
if (label.includes('BugFind')) label = 'Bug Find';
if (!phaseData[label]) return;
node.style.cursor = 'pointer';
node.addEventListener('click', () => showDetails(label));
});
}
function showDetails(phase) {
const panel = document.getElementById('details-panel');
const data = phaseData[phase];
if (!data) return;
let html = `
<div>
<div class="text-xl font-semibold text-white">${phase}</div>
<div class="text-xs text-zinc-500 mt-1 font-mono">${data.prompt}</div>
</div>
<div class="mt-6">
<div class="text-[10px] uppercase tracking-[1px] text-zinc-500 mb-2">Description</div>
<div class="text-sm leading-relaxed">${data.description}</div>
</div>
<div class="mt-6">
<div class="text-[10px] uppercase tracking-[1px] text-zinc-500 mb-2">Outputs</div>
<div class="inline-block text-sm font-mono bg-zinc-950 border border-zinc-800 px-4 py-2 rounded-xl">${data.outputs}</div>
</div>
`;
if (data.dependsOn.length > 0) {
html += `
<div class="mt-6">
<div class="text-[10px] uppercase tracking-[1px] text-zinc-500 mb-2">Depends On</div>
<div class="flex flex-wrap gap-2">
${data.dependsOn.map(f =>
`<span class="text-xs px-3 py-1 bg-zinc-950 border border-zinc-800 rounded-full">${f}</span>`
).join('')}
</div>
</div>
`;
}
panel.innerHTML = html;
}
function init() {
renderDiagram();
// Show Research by default after a short delay
setTimeout(() => {
const panel = document.getElementById('details-panel');
if (panel.innerHTML.includes('Select a phase')) {
showDetails('Research');
}
}, 900);
}
window.onload = init;
</script>
</body>
</html>