Initial commit: minimal agent framework
This commit is contained in:
+282
@@ -0,0 +1,282 @@
|
||||
# Onboarding a New Project
|
||||
|
||||
## Quick Checklist
|
||||
|
||||
- [ ] Create `.agent-framework/` directory in project root
|
||||
- [ ] Create `AGENT.md` (project level)
|
||||
- [ ] Create `RULES.md` (project level)
|
||||
- [ ] Run exploration ritual with agent (fresh session)
|
||||
- [ ] Agent reads global + project AGENT.md and RULES.md
|
||||
- [ ] Agent reports back
|
||||
- [ ] Create first `tasks/{task-name}/` folder
|
||||
- [ ] Start research phase using `prompts/research.md`
|
||||
|
||||
This is the exact sequence to follow when bringing any new project into the framework.
|
||||
|
||||
## Prompt Rendering Convention
|
||||
|
||||
All prompts are stored as template files in `~/.agent-framework/prompts/`. They use `{placeholder}` syntax.
|
||||
|
||||
### Placeholders
|
||||
|
||||
| Placeholder | Example | Description |
|
||||
|---|---|---|
|
||||
| `{project}` | `/home/laptran/ai-env/projects/invest-copilot` | Absolute path to the project root |
|
||||
| `{task-name}` | `fix-alert-test` | The task folder name (kebab-case) |
|
||||
| `{task-description}` | `Fix the alert test and complete sector rotation` | Brief description of what to do |
|
||||
|
||||
### How It Works
|
||||
|
||||
When you ask me to run a phase, I will:
|
||||
1. Read the template file (e.g., `~/.agent-framework/prompts/implement.md`)
|
||||
2. Replace all `{placeholders}` with actual values
|
||||
3. Execute the rendered prompt
|
||||
|
||||
You never need to copy-paste prompts. Just tell me what to do.
|
||||
|
||||
### Example
|
||||
|
||||
You say: *"Implement the sector rotation task"*
|
||||
|
||||
I do:
|
||||
```
|
||||
Read: ~/.agent-framework/prompts/implement.md
|
||||
Replace: {project} → /home/laptran/ai-env/projects/invest-copilot
|
||||
{task-name} → fix-alert-test-and-complete-sector-rotation
|
||||
{task-description} → Fix alert test and complete sector rotation service
|
||||
Execute: The rendered prompt
|
||||
```
|
||||
|
||||
## Scenario A: Existing Project (Drop-In)
|
||||
|
||||
Use this when the project already exists with code, tests, and structure.
|
||||
|
||||
### 1. Create the Project Framework Directory
|
||||
|
||||
```bash
|
||||
mkdir -p /path/to/project/.agent-framework
|
||||
```
|
||||
|
||||
### 2. Create the Two Required Files
|
||||
|
||||
Create these two files inside `.agent-framework/`:
|
||||
|
||||
#### AGENT.md (project level)
|
||||
```markdown
|
||||
# AGENT.md (project-name)
|
||||
|
||||
This project uses the global framework at ~/.agent-framework/.
|
||||
|
||||
Additional project rules are in RULES.md.
|
||||
|
||||
Default mode: research → implement → optional verification.
|
||||
```
|
||||
|
||||
#### RULES.md (project level)
|
||||
Start with any hard constraints you already know for this project. Keep it short.
|
||||
|
||||
Example:
|
||||
```markdown
|
||||
# RULES.md (project-name)
|
||||
|
||||
- Always separate research from implementation in fresh sessions.
|
||||
- Never assume existing code or schema — explore first.
|
||||
- [Add any other non-negotiables]
|
||||
```
|
||||
|
||||
### 3. Run the Initial Exploration Ritual
|
||||
|
||||
Give the agent this prompt in a fresh session:
|
||||
|
||||
```
|
||||
You have been given a new project at this path:
|
||||
/path/to/project/
|
||||
|
||||
Your first actions must be:
|
||||
|
||||
1. Explore the project root using ls and find.
|
||||
2. Read .agent-framework/AGENT.md
|
||||
3. Read .agent-framework/RULES.md
|
||||
4. Read ~/.agent-framework/AGENT.md
|
||||
|
||||
Report back with:
|
||||
- Confirmation the framework files were found and read
|
||||
- Summary of the project rules
|
||||
- What process this project expects
|
||||
- Key observations from the project structure
|
||||
|
||||
Do not start any task yet.
|
||||
```
|
||||
|
||||
### 4. If You Don't Know What Task to Do Next
|
||||
|
||||
Run a research phase whose goal is to discover the highest-value next task.
|
||||
|
||||
Tell me: *"Research the project and find the next task"*
|
||||
|
||||
I will:
|
||||
1. Read `~/.agent-framework/prompts/research.md`
|
||||
2. Replace `{project}` with the project path
|
||||
3. Set `{task-description}` to "Explore the project and identify the highest-value next task"
|
||||
4. Execute the rendered prompt
|
||||
|
||||
### 5. Pick the First Task
|
||||
|
||||
Once the agent has completed the exploration report (or discovery research), give me the first real task.
|
||||
|
||||
### 6. Create the First Task Folder
|
||||
|
||||
```bash
|
||||
mkdir -p /path/to/project/tasks/first-task-name/
|
||||
```
|
||||
|
||||
I will then produce `SPEC.md` inside that folder during the research phase.
|
||||
|
||||
## Scenario B: Starting From Scratch
|
||||
|
||||
Use this when you have an idea but no code yet.
|
||||
|
||||
### 1. Create the Project Framework Directory
|
||||
|
||||
```bash
|
||||
mkdir -p /path/to/project/.agent-framework
|
||||
```
|
||||
|
||||
### 2. Create the Two Required Files
|
||||
|
||||
#### AGENT.md (project level)
|
||||
```markdown
|
||||
# AGENT.md (project-name)
|
||||
|
||||
This project uses the global framework at ~/.agent-framework/.
|
||||
|
||||
Additional project rules are in RULES.md.
|
||||
|
||||
Default mode: research → implement → optional verification.
|
||||
```
|
||||
|
||||
#### RULES.md (project level)
|
||||
```markdown
|
||||
# RULES.md (project-name)
|
||||
|
||||
- Always separate research from implementation in fresh sessions.
|
||||
- Start with a minimal viable structure — no over-engineering.
|
||||
- [Add any other non-negotiables]
|
||||
```
|
||||
|
||||
### 3. Run the Discovery Research
|
||||
|
||||
Tell me: *"Help me design the initial architecture for a new project. Here's what I have in mind: {your idea}"*
|
||||
|
||||
I will:
|
||||
1. Read `~/.agent-framework/prompts/research.md`
|
||||
2. Replace `{project}` with the project path
|
||||
3. Set `{task-description}` to "Help design the initial architecture and first implementation task for a new project"
|
||||
4. Execute the rendered prompt
|
||||
|
||||
### 4. Review and Approve the Spec
|
||||
|
||||
Review the SPEC.md. If it looks good, proceed to implementation. If not, iterate.
|
||||
|
||||
### 5. Create the Task Folder and Implement
|
||||
|
||||
```bash
|
||||
mkdir -p /path/to/project/tasks/01-initial-setup/
|
||||
```
|
||||
|
||||
Then tell me: *"Implement the first task"* and I'll run the implementation phase.
|
||||
|
||||
### 6. Iterate
|
||||
|
||||
After the first task is complete, create the next task folder and repeat:
|
||||
|
||||
```bash
|
||||
mkdir -p /path/to/project/tasks/02-next-feature/
|
||||
```
|
||||
|
||||
## Phase Prompts (Template Files)
|
||||
|
||||
All phase prompts are stored as template files. I render them automatically.
|
||||
|
||||
### Phase 1: Research
|
||||
|
||||
**Template**: `~/.agent-framework/prompts/research.md`
|
||||
**Output**: `SPEC.md`
|
||||
|
||||
**Trigger**: *"Research {task-description}"*
|
||||
|
||||
### Phase 2: Implementation
|
||||
|
||||
**Template**: `~/.agent-framework/prompts/implement.md`
|
||||
**Output**: Code changes + test results
|
||||
|
||||
**Trigger**: *"Implement the {task-name} task"*
|
||||
|
||||
### Phase 3: Bug Finding (Optional)
|
||||
|
||||
**Template**: `~/.agent-framework/prompts/bug_finder.md`
|
||||
**Output**: `BUG_REPORT.md`
|
||||
|
||||
**Trigger**: *"Find bugs in the {task-name} task"*
|
||||
|
||||
### Phase 4: Referee (Optional)
|
||||
|
||||
**Template**: `~/.agent-framework/prompts/referee.md`
|
||||
**Output**: `VERDICT.md`
|
||||
|
||||
**Trigger**: *"Review the {task-name} task"*
|
||||
|
||||
## Core Principles (From the Original Article)
|
||||
|
||||
These principles underpin the entire framework. Internalize them.
|
||||
|
||||
### 1. Context Is Everything
|
||||
- Ruthlessly minimize what the agent sees. Irrelevant history, old notes, or too many skills destroys performance.
|
||||
- Separate research from implementation. Don't make one agent both figure out *what* to build and *how* to implement it in the same session.
|
||||
- Use fresh contexts/sessions per major task or "contract."
|
||||
|
||||
### 2. Handle Sycophancy (The "Desire to Please")
|
||||
Agents are optimized to be helpful and agreeable. This leads to a common failure mode: if you say "find me a bug," it will often find (or invent) one because it wants to deliver.
|
||||
|
||||
**Solutions:**
|
||||
- Use **neutral prompts** ("Search through the database, follow the logic of each component, and report all your findings") instead of leading ones.
|
||||
- Exploit it productively with a **multi-agent validation loop**:
|
||||
- Agent A (Bug Finder): Scored +1 / +5 / +10 based on severity. It becomes hyper-aggressive at finding issues.
|
||||
- Agent B (Adversarial): Gets points for every bug it successfully disproves, but loses double if wrong. It aggressively tries to shoot them down.
|
||||
- Agent C (Referee): Told you have ground truth; scores both previous agents. This yields very high-fidelity results.
|
||||
|
||||
### 3. Define Clear End States ("How to End a Task")
|
||||
Agents know how to start but not when to stop (they'll implement stubs and declare victory).
|
||||
|
||||
**Fixes:**
|
||||
- Heavy use of tests as milestones ("Task is not complete until these X tests pass. You are not allowed to delete or modify the tests.")
|
||||
- Create a **{TASK}_CONTRACT.md** that explicitly lists all acceptance criteria, tests, screenshots, etc. Make this the single source of truth for completion.
|
||||
- Use stop-hooks that prevent the agent from ending the session until the contract is satisfied.
|
||||
|
||||
### 4. Rules + Skills (The Actual Memory System)
|
||||
Treat your CLAUDE.md (or equivalent) as a lightweight router/directory, not a massive dump.
|
||||
|
||||
- **Rules**: Encode preferences and prohibitions ("If coding, read coding-rules.md first"). Make them conditional and nested.
|
||||
- **Skills**: Encode repeatable *recipes* ("This is exactly how we implement authentication" or "This is our research process").
|
||||
- Start minimal. Iteratively add rules/skills as you observe unwanted behavior.
|
||||
- When performance degrades (contradictions or bloat), have the agent consolidate, de-duplicate, and ask you to resolve conflicts.
|
||||
|
||||
### 5. Long-Running Agents
|
||||
24/7 autonomous agents often fail due to context accumulation and drift.
|
||||
|
||||
**Better pattern:**
|
||||
- One focused session per contract/task.
|
||||
- An orchestration layer that spawns new clean sessions.
|
||||
- Avoid throwing everything into one forever-running context.
|
||||
|
||||
### 6. Stay Current Without Chasing
|
||||
Just update your CLI regularly and read the release notes. If Anthropic/OpenAI add or acquire something (skills, memory, planning, etc.), pay attention. Most "new hot harness" hype becomes obsolete quickly.
|
||||
|
||||
## Notes
|
||||
|
||||
- Only create the two files in step 2. Do not copy the entire global framework.
|
||||
- The global `~/.agent-framework/` already contains the prompts and contracts.
|
||||
- Keep project RULES.md short and specific to this project.
|
||||
- Always start with a fresh agent session for each phase.
|
||||
- Phase 3 and 4 are optional but recommended for critical features.
|
||||
- Use `{task-name}_CONTRACT.md` for critical tasks to define explicit acceptance criteria.
|
||||
Reference in New Issue
Block a user