diff --git a/AGENT.md b/AGENT.md index c566e62..2c38153 100644 --- a/AGENT.md +++ b/AGENT.md @@ -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. \ No newline at end of file diff --git a/README.md b/README.md index 8d963bd..c5828d3 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/prompts/design.md b/prompts/design.md new file mode 100644 index 0000000..577aafc --- /dev/null +++ b/prompts/design.md @@ -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. \ No newline at end of file diff --git a/prompts/orchestrate.md b/prompts/orchestrate.md new file mode 100644 index 0000000..f6d73f1 --- /dev/null +++ b/prompts/orchestrate.md @@ -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". \ No newline at end of file diff --git a/references/session-starter.md b/references/session-starter.md new file mode 100644 index 0000000..409cfe9 --- /dev/null +++ b/references/session-starter.md @@ -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`. \ No newline at end of file diff --git a/system-prompt.md b/system-prompt.md new file mode 100644 index 0000000..66f7cbb --- /dev/null +++ b/system-prompt.md @@ -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. \ No newline at end of file diff --git a/visualize-3d.html b/visualize-3d.html new file mode 100644 index 0000000..f324d72 --- /dev/null +++ b/visualize-3d.html @@ -0,0 +1,285 @@ + + + + + + Agent Framework • 3D Sphere + + + + + +
+
+
Agent Framework
+
3D Phase Visualization
+
+
+ +
+ + + + +
+ Drag to rotate • Scroll to zoom • Click nodes +
+ + + + \ No newline at end of file diff --git a/visualize.html b/visualize.html new file mode 100644 index 0000000..a1e9d9e --- /dev/null +++ b/visualize.html @@ -0,0 +1,216 @@ + + + + + + Agent Framework • Routes + + + + + +
+
+
+

Agent Framework

+

Phase relationships and routing

+
+
~/.agent-framework
+
+ +
+ + +
+
+
Phase Graph
+
Click any node for details
+
+
+
+ + +
+
Phase Details
+
+
Select a phase to view its prompt, outputs, and dependencies.
+
+
+ +
+
+ + + + \ No newline at end of file